A (Page 1) ASTI V1.0 This subsystem is a component that manages the new "Service" interface and performs the communications between one or more client tasks and at least one service tasks. It is part of the basic configuration and is initially only released for internal purposes. Since the commands appear on the user interface they are described in this paper. There is no dedicated manual for ASTI, just this README file. Requirements Rep A0516426 is required for the termination jump in systems earlier than V15.0. The optional Rep A0526373 is required in all systems so that the /STA output is correctly output for job-dependent IDs. Contents 1 Introduction 2 2 Commands 3 2.1 Command Return Codes 3 2.2 Service Management 3 2.2.1 START-SERVICE Command 7 2.2.2 STOP-SERVICE Command 7 2.2.3 SHOW-SERVICE-STATUS Command 8 2.2.4 MODIFY-SERVICE-PARAMETER Command 9 2.3 Client Commands 9 2.3.1 SHOW-ORDER-STATUS Command 9 2.3.2 DELETE-ORDER Command 10 2.3.3 REQUEST-ORDER-RESULT Command 10 2.3.4 SEND-ORDER Command 11 2.4 Service Command 12 2.4.1 PROCESS-ORDER Command 12 3 Macros 12 A (Page 2) 1 Introduction ASTI is not a stand-alone system that directly provides a service to the customer. It is intended for subsystem developers that have to realize a type of client/server model. ASTI thereby provides the connection between the client and the server. Connections can be made in all directions (TU-TU, TPR-TU, TU-TPR and TPR-TPR). The client issues an order to the server and this is then processed by the server. ASTI takes care of the communications between the different tasks. ASTI takes the order and puts it into a wait queue for the service concerned. All parameters are stored. The service queries ASTI as to whether there is an order pending for it. If there is one for this service, it is forwarded to the service concerned. The service executes the function and reports the result to the client. The processes can be delivered either synchronously, i.e. the client waits for the result, or asynchronously. The client can also control how long the orders have to be held in the system before they are processed. An order is stored until it is processed. The client can also control how long the result of an order is stored. There are three options: 1.) The client does not want to receive a result; ASTI rejects the result. 2.) The client wants to receive the result during the service session. The return message is held in main memory and deleted after the service session is ended. 3.) The client wants to receive the result in all cases. The return message is stored on the disk. The return message is only deleted after it has been successfully delivered. A (Page 3) 2 Commands 2.1 Command Return Codes All commands have SUBCODE1(), SUBCODE2() and MAINCODE() set. If all is OK, the MAINCODE has the value CMD0001. If an error occurs the MAINCODE contains the key of the error message and the SKIP function is triggered. The service and the client commands also set SDF-P variables. These variables are only set in positive cases. SVTVAR-ORDERID SVTVAR-SERVICE SVTVAR-DATA 2.2 Service Management These commands are responsible for controlling the service concerned. The service can be started and stopped with them. It is also possible to output the status of the service and carry out a few modifications. 2.2.1 Command: START-SERVICE This command starts a service. A service is a batch job that is generated by ASTI and starts just one program. The program is defined by a symbol and a library. When the program terminates, the job also terminates. A (Page 4) START-SERVICE SERVICE-NAME= ,FROM-FILE= |*LIBRARY-ELEMENT(..) (LIBRARY=, SYMBOL=) |*BY-IMON(..) (LOGICAL-ID=SYSLNK | ,INSTALLATION-UNIT= ,VERSION=*STD | ,DEFAULT-LIBRARY= ,SYMBOL=) |*NONE(TSN= ) ,PROCESSING-ADMISSION= |*FROM-ORDER |*FROM-START(..) (USERID=*SAME | ,ACCOUNT=*SAME | ,PASSWORD=*SAME | *NONE | ) ,ALLOWED-USER = |*START-USER-IDENTIFICATION |*BY-GUARD(NAME=) |*NONE |*ALL ,ORDER-RECOVERY=*PARAMETER(..) (ALLOWED = *NONE | *SESSION-WIDE | *PERMANENT ,DEFAULT = *NONE | *SESSION-WIDE | *PERMANENT) ,ORDER-LIMIT= 255 | ,NUMBER-OF-TASKS= 1 | ,START-PARAMETER= *NONE | | ,NOT-ALLOWED-CMD= list-poss(5): *STOP-SERVICE | *MODIFY-SERVICE | *SEND-ORDER | *DELETE-ORDER | *REQUEST-ORDER-RESULT ,NOT-ALLOWED-SVC= list-poss(4): *SVTSTOP | *SVTSORD | *SVTDORD | *SVTRORD A (Page 5) FROM-FILE this parameter supplies the load library and the symbol to be loaded. Either direct input *LIBRARY-ELEMENT or indirect input via the installation monitor *BY-IMON are possible. The option *NONE can be used to make a running dialog task be seen as a service task. LIBRARY name of a module library. SYMBOL name of a CSECT or an ENTRY with which a module is loaded and started. LOGICAL-ID logical name of the module library. INSTALL-UNIT name of a product. VERSION version of a product. *STD is the highest installed version. DEFAULT-LIB default library name, if the product is not installed. TSN a TSN of a dialog task can be input here. PROCESSING-ADMISSION regulates which user environment the service works in. *FROM-START the service contains a user ID that is not changed during operation. USERID *SAME the user ID of the caller is taken over. the specified user ID is taken. ACCOUNT *SAME only meaningful with user ID=*SAME. account number of the user ID. PASSWORD *SAME only meaningful with user ID=*SAME. *NONE no password assigned. password of the user ID. *FROM-ORDER the service takes over the user environment of the task that sent the order. This function is not allowed for FROM-FILE=*NONE. ALLOWED-USER controls access to the service. *START-USER-IDENTIFICATION only the same user ID as with START-SERVICE is allowed. *BY-GUARD the user IDs are permitted via a guard. The guard is in the start user ID. The length of the guard is (1..8 Char). *NONE the service is started that only the service management uses. *ALL all tasks have access. NUM-OF-TASKS 1-16 number of service tasks that work for this service. SERVICE-NAME a name that is unique for this system. FSC services should begin with $. START-PARAM this parameter must be queried by the service after the service task is started. The record is used for initializing the service. A (Page 6) ORDER-RECOVERY the value range of the ORDER-RECOVERY parameter in the SEND-ORDER command can be influenced with this parameter. ALLOWED the value range of the ORDER-RECOVERY parameter in the SEND-ORDER command can be limited with this parameter. DEFAULT the ORDER-RECOVERY default value is set with this parameter. *NONE the ORDER and the RESULT are only held in main memory. If a task or the service dies, the orders concerned are acknowledged negatively. If the order task is missing, the results are deleted. *SESSION-WIDE the ORDER is held in memory until the order has been processed. Unprocessed orders and results are held in main memory and only deleted after SESSION-END (/SHUTDOWN or /STOP-SUB ASTI). *PERMANENT the ORDER and the RESULT are stored on the disk. Each part is only deleted after the respective action is completed. With this function, incorrect programming can create order cadavers that remain in the order user ID in the form of files. ORDER-LIMIT this defines the maximum number of ORDERS being processed. NOT-ALLOWED-CMD specific commands can be blocked for a service with this parameter. *STOP-SERVICE this service cannot be stopped with this command. *MOD-SERVICE this service cannot be modified. *SEND-ORDER no order can be placed to this service. *DELETE-ORDER no orders can be deleted. *REQ-ORDER-RESULT no results can be fetched. NOT-ALLOWED-SVC program calls for a service can be blocked with this parameter. *SVTSTOP this service cannot be stopped by the program. *SVTSORD no orders can be placed by the program. *SVTDORD no orders can be deleted by the program. *SVTRORD no results can be fetched by the program. Note: The TPR interface is not subject to any of these restrictions A (Page 7) 2.2.2 Command: STOP-SERVICE This command stops a service. The service is set to termination mode. The separate tasks must stop themselves. New orders are no longer accepted. Existing order are handled according to the save order value. STOP-SERVICE SERVICE-NAME= SERVICE-NAME name of service 2.2.3 Command: SHOW-SERVICE-STATUS The status of a single service or of all services are displayed with this command. SHOW-SERVICE-STATUS SERVICE-NAME = *ALL | SERVICE-NAME selection to all or a specific service. Output SERVICE-NAME=*ALL SID SERVICE_NAME STATUS ADMINSTR ALLOWED_USER PROCESSING MODE @001 SEND-MAIL RUNNING TSOS ALL FROM_ORDER DIALOG @002 SERVICE IN_CREATION ELBRM ALL FROM_ORDER SERVICE Output SERVICE-NAME=SEND-MAIL SID SERVICE_NAME STATUS ADMINSTR ALLOWED_USER PROCESSING MODE @001 SEND-MAIL RUNNING TSOS ALL FROM_ORDER DIALOG SYMBOL: XYZSEND LIBRARY: SYSLNK.SEND-MAIL.015 GUARD: *NONE TASK: 0ADA ACT_ORDER: 000 TERMINATION: NONE START_PARAM: NONE TASK: 0ADB ACT_ORDER: 001 TERMINATION: NONE START_PARAM: NONE A (Page 8) 2.2.4 Command: MODIFY-SERVICE-PARAMETER MODIFY-SERVICE-PARAMETER SERVICE-NAME = ,ALLOWED-USER = |*START-USER-IDENTIFICATION |*BY-GUARD(NAME=) |*ALL |*UNCHANGED ,NUMBER-OF-TASKS= 1 | | *UNCHANGED ,ORDER-LIMIT= | *UNCHANGED ,START-PARAMETER= *NONE | | | *UNCHANGED SERVICE-NAME name of service ALLOWED-USER controls who can use the service. NUM-OF-TASKS 0-16 number of service tasks that can work with the same SERVICE name. The number of tasks can be reduced to 0. In this case, the service is still present and accepts orders, but does not execute them. This parameter is ignored with a dialog service. ORDER-LIMIT the number of orders for this service that are in the system can be limited with this parameter. START-PARAMETER the initialization parameters can be changed with this parameter. The next PROCESS-ORDER job receives the RC: new parameter. If a PROCESS-ORDER is in the wait queue when the parameters are modified, RC: 00040010 is only set after the queue timeout. A (Page 9) 2.3 Client Commands These commands connect the client to the service. 2.3.1 Command: SHOW-ORDER-STATUS Information about orders is output with this command. The command functions asynchronously to normal operation and consistency between the number of orders and the separate sub-queues is therefore not assured. SHOW-ORDER-STATUS INFORMATION = *SUMMARY ( SERVICE-NAME = *ALL | ) *ORDER-LIST ( SERVICE-NAME = *ALL | ) *ALL ( ORDER = < x-text 1..16 > ) INFORMATION: *SUMMARY counter with the number of orders *ORDER-ID all relevant order IDs, including status *ALL information about the orders (administrator about all, normal user about his own) SERVICE-NAME name of the service ORDER-ID order during this subsystem session, the last 1..8 bytes order from other session (16 bytes) Output information *SUMMARY SERVICE ALL-Q RDY-Q ACT-Q RES-Q WAI-Q NRR-Q IAC-Q DEQ-R $ELB 2 1 1 0 0 0 0 0 ALL-Q all orders of this service RDY-Q all orders that are waiting for execution by the service ACT-Q all orders that are currently being executed RES-Q all results that have not been fetched yet WAI-Q all orders that have been deferred NRR-Q all results that have not been requested IAC-Q orders from stopped service (session-wide) DEQ-R results whose tasks no longer exist Output information *ORDER-LIST ORDER-ID SERVICE QUEUE TSN 008405C900000002 $ELB READY_QUEUE 0AEZ 008405C900000001 $ELB ACTIVE_QUEUE 0AEZ Output information *ALL ORDER-ID SERVICE QUEUE 008405C900000002 $ELB READY_QUEUE USERID ACCOUNT TSN USER_STATE TSOS ADMINSTR 0CT4 RESULT_REQUESTED USERID user ID of the sender ACCOUNT account of the sender TSN sender task USER-STATE should results be returned A (Page 10) 2.3.2 Command: DELETE-ORDER Either one ORDER or all ORDERS of a service can be deleted with this command. With a normal user, only orders with his user ID are deleted and with the administrator, all orders of the service concerned. DELETE-ORDER ORDER-ID= |*ALL(SERVICE-NAME=) |*USER(SERVICE-NAME=) |*TASK(SERVICE-NAME=) ORDER-ID order during this system session, the last 1..8 bytes; order from another session (16 bytes). Only orders from the same task are deleted. Exception: permanent orders, whose callers no longer exist. *ALL(SERVICE-NAME=) all orders that were sent to the service by this user ID are deleted; with the administrator, all orders are deleted. Exception: permanent orders from external tasks (administrator checking is not possible). *USER(SERVICE-NAME=) all orders that were sent to the service by this user ID are deleted, including permanent orders. *TASK(SERVICE-NAME=) all orders that this task sent to the service are deleted, including permanent orders. Note: All orders concerned are searched for and marked with "order to delete". Orders that are currently being processed by the service are completed by the service. If the client is waiting, the result is delivered. If the client is not waiting, the result is deleted. Orders in the ready queue or in the wait queue are deleted. If the client is waiting for the result, ASTI delivers a negative result (key: SVTS903). 2.3.3 Command: REQUEST-ORDER-RESULT The result of an asynchronous order is fetched with this command. The result is thereby deleted in the ASTI management. Results of permanent orders whose caller task no longer exists can also be fetched with this. REQUEST-ORDER-RESULT ORDER-ID= | *TASK(SERVICE-NAME=) | *USER(SERVICE-NAME=) ,WAIT-FOR-RESULT= *YES | *NO ORDER-ID order during this subsystem session, the last 1..8 bytes; order from other session (16 bytes). *TASK the next order of this task is requested *USER the next order of this user ID is requested SERVICE-NAME selects the service WAIT-FOR-RESULT the client waits for the result With the *USER parameter, results whose task no longer exists can be fetched. A (Page 11) 2.3.4 Command: SEND-ORDER An order is placed with this command. SEND-ORDER SERVICE-NAME = ,WAIT-FOR-RESULT=*YES | *NO (RESULT = *NO | *YES) ,ORDER-RECOVERY=*STD | *NONE | *SESSION-WIDE | *PERMANENT ,DATA= | | *NO SERVICE-NAME name of the service. WAIT-FOR-RESULT *NO the order is accepted and processed asynchronously. A result can be expected that must then be fetched later with /REQUEST-ORDER-RESULT. *YES the order is accepted and the task waits until the order is completed. The result is displayed. ORDER-RECOVERY *NONE no special measures are met regarding transaction security. *SESSION-WIDE the order is retained until acknowledged by the service and the result is also retained until delivery to the client. If these events do not occur, the order or the result is deleted when the service ends. *PERMANENT in contrast to *SESSION-WIDE, nothing is deleted. The orders are still available in the next service session. *STD the default value of /START-SERVICE is taken. DATA the contents of the parameter represent the order to the service task. A (Page 12) 2.4 Service Command 2.4.1 Command: PROCESS-ORDER The service fetches orders from ASTI and returns results with this command. PROCESS-ORDER ACTION= *GET-ORDER(WAIT-FOR-ORDER=*YES | NO) *SEND-ACK (ORDER-ID=,RETURN-DATA= *NONE | ,RETURN-KEY=) *SEND-RETRY(ORDER-ID=,WAIT-TIME= *GET-START-PARAMETER *SEND-ACK order with ORDER ID was executed correctly. RETURN-DATA return parameter. *NONE no value is returned. *SEND-NAK order with ORDER ID was aborted with an error. The error is specified in the RETURN-KEY field. *SEND-RETRY the order can temporarily not be executed. It should be restarted in n seconds. WAIT-TIME = time in seconds. The wait time may extend up to the queue timeout (30 seconds). *GET-ORDER request a new order. WAIT-FOR-ORDER *YES the service task waits until a new order arrives. *NO the service task checks whether a new order is pending and continues working immediately. *GET-START-PARAMETER initialization parameters are queried after the service start or after a request via RC. 3 Macros There are also macros available for the interfaces but they will not be described for the time being.