5.41.3 AxesTerminalService Scripts
The AxesTerminalService provides service commands that permit your client application to interact with your 5250 application via aXes in virtually any way necessary.
However, most of the service commands perform a single operation amongst several or many that may be necessary to complete just one screen interaction. For example, the SETBYNAME or SETBYPOS service commands let you set the value in a 5250 screen entry field, but only a single field for each execution.
This level of interface provides the most flexibility to your application. At each and every operation, your program remains in control, and can branch to different execution paths based on the outcome of every screen interaction.
On the other hand, however, if every aXes terminal operation was to be executed this way, the amount and complexity of the code in your application may become excessive in a non-trivial implementation. In addition, the number of JSM commands that your application needs to execute may begin to adversely affect the performance of your solution.
To enable you to choose the appropriate balance amongst the considerations of flexibility, complexity and performance, the AxesTerminalService provides support for aXes terminal operations scripts. This support is provided through two specialized service commands:
- The LOADSCRIPT command loads an aXes terminal operation script into the service for use in subsequent EXECUTE commands.
- The EXECUTE command executes a specified routine in an aXes terminal operation script.
Using this support, your application can replace a series of SETBYNAME or SETBYPOS commands that populate one entry screen, for example, with a single EXECUTE command. You can retain the degree of control necessary for your application and branch based on the outcome of 5250 screen operations by (optionally) breaking up your script into separate routines that are executed separately. For example, you may define a script routine to complete each non-trivial 5250 data entry screen. For a data entry screen containing a subfile, you might define a routine to complete each subfile record or line.
Typically, an implementation would define one script (optionally consisting of multiple routines), load the script once using the LOADSCRIPT command and execute the routines as required using the EXECUTE command. However, you may load and execute the scripts using the EXECUTE command if you prefer. You may also mix this approach with direct use of the other service commands such as SETBYNAME, SETBYPOS, and SEND.
The script is provided as a list (for a LANSA RDML/X client, a working list) that is passed to the service with the LOADSCRIPT and/or EXECUTE commands. The list must contain a minimum of eight fields/columns and may contain up to twelve. The purpose and meaning of the list fields/columns that make up an aXes terminal operations script is described below.
|
1. Routine name |
Specifies the name of a routine to which this aXes terminal operations script line belongs. Lines for a routine must be specified contiguously in the list. The routine name is optional in the script and in the ROUTINE keyword of the EXECUTE command. |
|
2. Label name |
This column may specify a unique (within a routine) label associated with the line. This label may be referenced as the next action on success or failure of other lines in the same routine/script. |
|
3. Operation |
Specifies the aXes terminal operation performed by this script line. It may be one of the following: GET (gets a field value) SET (sets a field value) SEND (sends data to the aXes terminal server) Lines containing any other value in the Operation column are ignored. |
|
4. Field name |
(GET/SET) This column may specify the name of the field whose value is to be set or retrieved. The name may be a user-defined name (if an aXes project name was specified on the CONNECT command) or an aXes field identifier. If the field name is not specified for a GET or SET operation, then the field row and column must be specified. |
|
5. Field index |
(GET/SET) If the field named in the previous column is contained in a subfile, this column may specify the index of the instance on the current screen of the field whose value is to be set or retrieved. The first instance on the current screen has an index of 1, irrespective of the scroll position of the subfile. If your program needs to process fields in subfiles, it must do so one screen at a time and send ROLL_UP/ROLL_DOWN using the SEND command (just like a 5250 terminal user would have to do). |
|
6. Field row |
(GET/SET) This column may specify the screen row number of the field whose value is to be set or retrieved. The row and column together, if used, must refer to the first position of the required field. The value of this column is ignored if the field name is specified. Conversely, if the field name is not specified, then the field row and column must be specified. |
|
7. Field column |
(GET/SET) This column may specify the screen column number of the field whose value is to be set or retrieved. The row and column together, if used, must refer to the first position of the required field. The value of this column is ignored if the field name is specified. Conversely, if the field name is not specified, then the field row and column must be specified. |
|
8. Field value |
(SET) This column may specify the literal value to be set in the specified field. |
|
9. Field value |
(GET/SET) This column may specify the name of a field exchanged between your client program and the JSM that will receive (GET) or provide (SET) the value for the specified screen field. You will usually need to specify SERVICE_EXCHANGE(*FIELD) in the command string in order to receive the return value into your client program variable. |
|
10. Function key |
(SET/SEND) If a value is specified in this column, the operation will send the current aXes screen data to the aXes terminal server using the function key specified (after successfully setting the field value for a SET operation). You may use any of the function key values shown for the SETBYNAME, SETBYPOS and SEND commands. |
|
11. Action on success |
This column may be used to control the next script routine operation performed when this operation completes successfully. It may be one of the following: *NEXT (the script proceeds to the next line in the same routine) *ERROR (the script execution ends with an error status). Any other non-blank value is interpreted as the Label name of another script line in the same script routine, and the script continues with the first line in the script routine that matches the specified label. If no value is specified, *NEXT is assumed. |
|
12. Action on error |
This column may be used to control the next script routine operation performed when this operation ends in error. It may be one of the following: *NEXT (the script proceeds to the next line in the same routine) *ERROR (the script execution ends with an error status). Any other non-blank value is interpreted as the Label name of another script line in the same script routine, and the script continues with the first line in the script routine that matches the specified label. If no value is specified, *ERROR is assumed. |