am_read_expression_manager

Use this utility to: Generate and update Access Manager (AM) read expressions. Re-compute out-of-date read expressions. Attach read expressions to specified objects. Run in daemon mode and keep updating read expressions, as needed, based on changes to the associated objects. You can execute this utility in one of the following modes: onetime (standalone) Processes all dirty read expressions and optionally deletes unreferenced read expressions. daemon Processes periodic checks for dirty read expressions, as needed. create Provides a file with UIDs resulting from query output or other input parameters in order to generate read expressions for these objects. statistics Generates a report with general usage data for read expressions. Siemens Digital Industries Software recommends best practices to optimize read expression generation using this utility. Syntax am_read_expression_manager [-u=user-ID {-p=password | -pf=password-file} -g=group] [-mode=onetime | daemon | create | stop | status | statistics] [-batchSize=size] [-sleepTime=time-in-seconds] [-startTime=HH:mm:ss] [-endTime=HH:mm:ss] [-filePath=filename] [-active_project] [-saved_after=MM-DD-YYYY] [-dryRun] [-savedQuery=query] [-delete_unreferenced] [-h] Arguments -u Specifies the user ID. This is a user with Teamcenter administration privileges. Note If Security Services single sign-on (SSO) is enabled for your server, the -u and -p arguments are authenticated externally through SSO rather than being authenticated against the Teamcenter database. If you do not supply these arguments, the utility attempts to join an existing SSO session. If no session is found, you are prompted to enter a user ID and password. -p Specifies the password. This argument is mutually exclusive with the -pf argument. -pf Specifies the password file. For more information about managing password files, see Manage password files. This argument is mutually exclusive with the -p argument. -g Specifies the group associated with the user. If used without a value, the user's default group is assumed. -mode Specifies the mode for running the utility. Because the report is written to the syslog file, set the TC_KEEP_SYSTEM_LOG preference to true to retain the syslog file. onetime Exits after one time invocation; there is no repeated processing or daemon mode execution. daemon Periodically checks for stale read expressions and processes these as needed. After a configurable pause time, the utility is re-executed. (See comments on batchSize and sleepTime.) create Certain objects of interest are associated to read expressions if they do not already exist. Input can be a UID file, saved query or other input parameters. (See documentation for the -savedQuery, -filePath, -active_project and -saved_after arguments.) stop Stops the read expression daemon gracefully. status Returns a status, which validates whether the daemon is running. statistics Displays various relevant data related to read expressions, such as counts, number of unique expressions, maximum length, breakdown by class, and so forth. Statistics output also contains information on counts of unsupported read expressions. For example, the output may include instances of read expressions for objects where unsupported accessor terms are represented. In addition, this output can include parameterized read expressions, where lists of project team UIDs are compacted into a string alias. -batchSize=size For oneTime and daemon modes, this is the maximum size of a batch of objects having their read expressions updated in a single transaction. In these modes, the default size is 10000. -sleepTime=time-in-seconds For the daemon mode, this argument specifies the wait time until a new update task is executed. The default is 10 seconds. -startTime=HH:mm:ss For the daemon mode, this argument specifies the start (00:00:00 to 23:59:59) of the interval during which daemon read expression regeneration is active. A best practice is to use a time interval during which less business operations are executed. The default is unset. -endTime=HH:mm:ss For the daemon mode, this argument specifies the end (00:00:00 to 23:59:59) of the interval during which daemon read expression regeneration is active. A best practice is to use a time interval during which less business operations are executed. The default is unset. -filePath=filename Specifies an input file containing the UIDs of objects that need to be processed. This is relevant to the create mode. -active_project For the create mode, this argument gathers all workspace objects in the active project and applies read expressions if they do not already exist. -saved_after=MM-DD-YYYY For the create mode, this argument gathers all workspace objects that were the final version saved after the specified date and applies read expressions if they do not already exist. -dryRun For the create mode, this performs the associated queries, but it only outputs the number of found objects. It does not actually create the read expression associations for them. Note This argument is recommended for any create operation so that the system is protected from potentially very large numbers of found objects for read expressions. If your query returns more than 1M objects, it is recommended that you either re-formulate or filter the object list further. -savedQuery=query-name For the create mode, this argument executes the specified saved query and, then applies read expressions to the respective objects using the output list of tags. Optionally, if the saved query requires input parameters, these can also be specified in sequence using additional matching -name and -value command line parameters. -delete_unreferenced For daemon or oneTime mode, this argument deletes all unreferenced read expressions, for example, read expressions where the object_uid no longer exists in the database. -h Displays help for the utility. Read expression manager concurrency mode Read expression processing in concurrency mode (for example, parallel execution) is supported under certain conditions. If the identified number of stale read expressions exceeds the threshold set by the RE_MGR_concurrency_objs_threshold preference, the read expression manager process spawns five subprocesses. These sub-processes execute read expression generation in parallel, thereby improving the performance of read expression generation. Once the identified number of stale read expressions drops below the designated threshold, execution reverts back to a single process. Examples Use a UID input file to generate read expressions: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=create -filePath=path-to-input-file Create read expressions for all workspace objects in an active project: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=create -active_project Create read expressions for all workspace objects saved after May 2, 2020: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=create -saved_after=05-02-2020 Create read expressions for all items with a unique ID: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=create -savedQuery="Item ID" -name="Item ID" -value=item_id Output the number of found objects without creating the read expression associations for them: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=create -saved_after=05-02-2020 -dryRun Update stale read expressions: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=onetime Update stale read expressions using a daemon with interval and batch settings, where 7200 seconds equals 2 hours of sleep time between subsequent execution of the daemon update: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=daemon -batchSize=1000 -sleepTime=7200 Update stale read expressions using a daemon with sleep start/end time interval between 2 AM and 4 AM as active time for updates, with a sleep time of 10 seconds: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=daemon -batchSize=1000 -sleepTime=10 -startTime=02:00:00 -endTime=03:59:59 Output statistics: Copy am_read_expression_manager -u=user-ID -p=password -g=group -mode=statistics To exit a running daemon process, you must create a file with content containing the following name and location. Example: Copy %TC_ROOT%\log\am_read_expr_graceful_exit.tmp The daemon process checks for the existence of this file and exits if found. You must delete this file before you run the daemon process again. Related Topics Data Access Management