The program statements in CALLUTM are read by the SDF user interface and processed by the SDF command processor. Alongside the standard SDF statements, CALLUTM can also use any of the program statements listed in the table below:
No. | Program statement | Function |
1. | CREATE-CONFIGURATION | Defines the environment for the program run and selects the connection to the UTM application. This statement must be issued as the first statement. |
2. | SELECT-SERVICE | Starts a service (transaction code) in the UTM application. A message (operands or parameter values) can also be issued with this statement. |
3. | CONTINUE-SERVICE | Continues a service that is not yet completed. For services which consist of a number of processing steps, this statement starts the next processing step once the previous one is completed. A message can also be issued with this statement. |
4. | DEALLOCATE-CONVERSATION | Terminates the conversation with the UTM application. Any service that is still open in the UTM application and that belongs to this conversation will be terminated abnormally. |
5. | SHOW-CONFIGURATION | Displays the program runtime environment that was set with CREATE-CONFIGURATION or MODIFY-CONFIGURATION. |
6. | MODIFY-CONFIGURATION | Modifies the program runtime environment that was set with CREATE-CONFIGURATION. |
7. | CALLUTM-ERROR-STEP | Controls statement processing of CALLUTM in procedure or batch mode. |
CREATE-CONFIGURATION must always be the first statement to follow the program start. It is particularly important to ensure that CREATE-CONFIGURATION is issued before the SELECT-SERVICE statement.
Statements 5 and 6 can be issued anywhere between CREATE-CONFIGURATION and the end of the program run.
The statements are listed below in alphabetical order and described in detail.
Notational conventions
The following description of the statements uses SDF syntax notation. The table below outlines the elements that make up this form of notation, which are also described in the general section on in "Notational conventions".
Symbol | Meaning | Examples | |||||||||||||||||||||||||||||||||||||||||||||||||
< > | Angle brackets indicate variables whose values are described in terms of data types and the associated information. | POSITION = <integer 1..256> | |||||||||||||||||||||||||||||||||||||||||||||||||
/ | The slash character separates operand values that can be used as alternatives. | SET-TEST-MODE = *NO / *YES | |||||||||||||||||||||||||||||||||||||||||||||||||
(...) | Parentheses indicate operand values which begin a structure. | ,SET-SERVICE-JV = *YES (...) / *NO | |||||||||||||||||||||||||||||||||||||||||||||||||
Indentation | Indentation indicates dependency on the next highest operand. |
| |||||||||||||||||||||||||||||||||||||||||||||||||
| A vertical line indicates operands that belong together in a structure. It runs from the start to the end of a structure. |
| |||||||||||||||||||||||||||||||||||||||||||||||||
Short name: | The following name is a guaranteed alias name for the statement name. | Short name: CONFATTR | |||||||||||||||||||||||||||||||||||||||||||||||||
CALLUTM-ERROR-STEP
The program statement CALLUTM-ERROR-STEP controls statement processing of CALLUTM in procedure or batch mode:
If an error (other than SDF syntax error) occurred during CALLUTM program run, e.g. if the addressed UTM application is offline, CALLUTM reads the following program statements from SYSDATA, until CALLUTM-ERROR-STEP is recognized. If no CALLUTM-ERROR-STEP is found, CALLUTM will terminate.
The CALLUTM-ERROR-STEP statement has no operands.
Example
//CREATE-CONFIGURATION ... // ... // ... //SELECT-SERVICE SERVICE-NAME = KDCINF, SERVICE-DATA = C'STAT' (1) //SELECT-SERVICE SERVICE-NAME = KDXINF, SERVICE-DATA = C'USER' (2) //SELECT-SERVICE SERVICE-NAME = KDCINF, - (3) // SERVICE-DATA = C'USER,L=KDCCON' //CALLUTM-ERROR-STEP (4) //SELECT-SERVICE SERVICE-NAME = KDCINF, SERVICE-DATA = C'TAC' (5)
Explanation:
Statement (1) is executed.
Statement (2) causes an error, because TAC KDXINF is not defined.
Statement (3) is not executed.
The processing is continued with statement (5).
CONTINUE-SERVICE
CONTINUE-SERVICE allows you to continue a service that was started in the UTM application with SELECT-SERVICE and is made up of several steps. CONTINUE-SERVICE needs to be specified when the service sends a message to CALLUTM after one dialog step is completed but when the service as a whole is not yet completed because other processing steps remain to be executed. Data can be passed to the service for the next processing step.
CONTINUE-SERVICE | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
For a description of the operands, see the SELECT-SERVICE statement ("Description of CALLUTM program statements (BS2000 systems)").
Example
This example refers to the sample administration program SUSRMAX which is supplied with openUTM (see "Sample programs"). The dialog with SUSRMAX consists of the following steps:
SUSRMAX is started and returns a message prompting you to select a function:
-> //SELECT-SERVICE SERVICE-NAME=SUSRMAX <date: 04-19-2019 time: 11:21:03 application: DB400 host: BS2HOSTA tac: SUSRMAX ------------------------------------------------------------------- available commands: 0 = end | 1 = show-connected-users 2 = show-users-in-conversation | 3 = show-changeable-max-values 4 = change-max-values | please make a selection
The service is continued with CONTINUE-SERVICE; the function “1 = show-connectedusers” is selected (SERVICE-DATA='1'). openUTM returns the requested information.
-> //CONTINUE-SERVICE SERVICE-DATA='1' <- ... ... Output ...The UTM message prompting you to select another function is output again.
-> //CONTINUE-SERVICE <- ... ... The function selection message is output as in 1. ...The service is continued with CONTINUE-SERVICE; the function ”2 = show-users-inconversation” is selected (SERVICE-DATA='2'). openUTM returns the requested information.
-> //CONTINUE-SERVICE SERVICE-DATA='2' <- ... ... Output ...SUSRMAX is terminated (function “0 = end”).
-> //CONTINUE-SERVICE SERVICE-DATA='0' <date: 04-19-2019 time: 11:22:34 application: DB400 host: D018ZE08 tac: SUSRMAX ---------------------------------------------------------------- conversation terminated ---------------------------------------------------------------- -> //
CREATE-CONFIGURATION
The statement CREATE-CONFIGURATION defines the environment for the program run and selects the connection to the UTM application. In other words, it allows you to determine:
how the program is to sign on to the UPIC carrier system
the UTM application to which a connection is to be established
the UTM user ID to be passed when the conversation is established
whether and to what extent a log file is to be written
whether UPICTRACE is also to run.
CREATE-CONFIGURATION must be the first statement issued when the program has started. If CREATE-CONFIGURATION is issued repeatedly during the course of the program run, any open log files will be closed and open services will be rolled back. An internal DEALLOCATE is also executed.
You can use MODIFY-CONFIGURATION during a program run to modify the values set with CREATE-CONFIGURATION.
CREATE-CONFIGURATION | Alias: CONFATTR | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
LOCAL-NAME = <alphanum-name 1..8> | ||
Local name under which CALLUTM signs on to the UPIC carrier system. This name must be defined in the UPICFILE. | ||
SYMB-DEST-NAME = <alphanum-name 8..8> | ||
Symbolic partner name of the UTM application to which a connection is to be established. This name must be defined in the UPICFILE. | ||
USER-ID = | ||
UTM user ID used to establish the conversation. | ||
*NONE | No security functions are used. | |
<alphanum-name 1..8>( ) / <c-string_1..8_with-low> / < x-string 1..16> | ||
UTM user ID. This user ID must exist in the UTM application. PASSWORD = *NONE PASSWORD = <c-string 1..16> or <x-string 1..32> | ||
WRITE-LOGGING-FILE = | ||
Determines whether and to what extent the flow of data from the client to the server and back (i.e. service data) is to be logged. | ||
*NO | No data is logged. | |
*YES ( ) | Data is logged. LOGGING-FILENAME = <full-filename-without-gen-vers 1..54> OPEN-MODE = *EXTEND OPEN-MODE = *REPLACE LOGGING-INFO = *SEND LOGGING-INFO = *RECEIVE LOGGING-INFO = *ALL RECORD-LENGTH = *STD / <integer 1..252> | |
WRITE-UPIC-TRACE = | ||
Indicates whether UPIC tracing is to be activated. | ||
*NO | The UPIC trace is not activated. | |
*YES | The UPIC trace is activated. If no *UPICTRA link name to a job variable exists, a new job variable JV.UPICTRACE.CALLUTM is created with the value “-SX” and the link name *UPICTRA is assigned to it. | |
CONFIGURATION-ID = 1 | ||
Serves to identify the configuration. The only permissible value is 1. | ||
SET-TEST-MODE= | ||
Activate/deactivate test mode. | ||
*NO | Test mode is not activated. No UPIC calls are output to SYSOUT. | |
*YES | Test mode is activated. All UPIC calls from CALLUTM are output to SYSOUT. | |
SET-ENCRYPTION-LEVEL= | ||
Specifies whether and how data is to be encrypted over the connection. If encryption has been generated on the server side for the client connection, the relevant encryption level from the generation must be specified here. If encryption has been generated on the server side for a TAC that is to be called here, the encryption level must also be specified on the client side. | ||
*NO | No encryption. | |
<integer 1..4> | ||
Encryption level from the generation. | ||
Example
//CREATE-CONFIGURATION LOCAL-NAME=UPCPT#T0,SYMB-DEST-NAME=DBSADMT0, - // WRITE-LOGGING-FILE=*YES(L-F=LOG.CALLUTM)
DEALLOCATE-CONVERSATION
This statement terminates the conversation with the partner application. Any service that is still open in the UTM application is terminated abnormally.
DEALLOCATE-CONVERSATION |
CONFIGURATION-ID = 1 / <integer 1..1> |
CONFIGURATION-ID does not need to be specified (default setting).
Only CONFIGURATION-ID=1 may be specified.
Example
//DEALLOCATE-CONVERSATION
MODIFY-CONFIGURATION
MODIFY-CONFIGURATION allows you to modify the existing values set with CREATE-CONFIGURATION or a previous MODIFY-CONFIGURATION statement in the program runtime environment.
MODIFY-CONFIGURATION | Alias: MODATTR | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
For a description of the operands, see statement CREATE-CONFIGURATION on "Description of CALLUTM program statements (BS2000 systems)".
Example
Logging is deactivated.
-> //MOD-CONF WRITE-LOGGING-FILE=*NO <- CUA0050: configuration modified -> //
SELECT-SERVICE
SELECT-SERVICE starts a service in the UTM application. Data (i.e. operands and parameter values) required by the service for processing can also be supplied. In addition, a job variable can be defined to accept the receive message, segment of the receive message or any specified string once the statement has been executed. If the job variable defined has not yet been cataloged a new one is created.
If you use SELECT-SERVICE to call a service which consists of several processing steps and which passes dialog messages to CALLUTM between the individual processing steps, then, between the time the service is called and the time when it is terminated, you can (with the exception of the standard SDF statements) only issue the following statements:
CONTINUE-SERVICE
Continues the service once a dialog message has been received.DEALLOCATE-CONVERSATION
Aborts the connection and (abnormally) terminates the service in the UTM application.SHOW-CONFIGURATION
Reads the current configuration data.
SELECT-SERVICE | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SERVICE-NAME = <alphanum-name 1..8>/<c-string-with-lower-case> | ||
The transaction code with which the service is to be started in the UTM application; can also be an administration command or a different administration TAC. | ||
SERVICE-DATA = | ||
Message to be passed to the service in the UTM application. | ||
*NO | No message data is passed. | |
list-poss(42): <c-string-with-lower-case 1..1800> | ||
Message to be passed from the remote service. The message must be passed as a C string, i.e. enclosed in quotes. You can also pass a list of C strings here. The individual elements of the list are sent as partial messages and also received as partial messages by the server. Number of C strings: up to 42. Total length of the list: up to 1800 characters | ||
SET-SERVICE-JV = | ||
Supplies data to a job variable. | ||
*NO | Data is not supplied to a job variable. | |
*YES ( ) | Data is supplied to a job variable. JV-IDENTIFICATION = *JV-NAME ( ) JV-NAME = <full-filename-without-generation-version 1..54> POSITION = 1 POSITION = <integer 1..256> LENGTH = *REST LENGTH = <integer 1..256> JV-IDENTIFICATION = *LINK-NAME ( ) LINK-NAME = <alphanum-name 1..7> POSITION = as for *JV-NAME ( ); see above LENGTH = as for *JV-NAME ( ); see above PASSWORD = *NONE PASSWORD = <c-string 1..4> / <x-string 1..8> VALUE = *RECEIVE-MSG (POSITION = 1/<integer 1..4000>) VALUE = <c-string 1..256> / <x-string 1..512> | |
Note on the use of job variables
Before the statement is executed, the job variable is initialized with blanks as of the specified position and to the specified length. If an error occurs during this access to the job variable, the statement as a whole is not executed.
Example
The administration command KDCSHUT WARN, TIME=01 is called.
//SELECT-SERVICE SERVICE-NAME=KDCSHUT, SERVICE-DATA='WARN,TIME=01'The command KDCINF reads the properties of the user ID UPCUSER (KDCINF USER,LIST=UPCUSER). The output is to be written to the job variable JV.USER (as of column 81).
//SELECT-SERVICE SERVICE-NAME=KDCINF, - // SERVICE-DATA='USER,LIST=(UPCUSER)', - // SET-SERVICE-JV=*YES ( - // JV-ID=*JV-NAME ( - // JV-NAME=JV.USER, - // POSITION=81 ) - // ) - // VALUE=*RECEIVE-MSG(POSITION=161)
Result
Once the statement has executed, the job variable JV.USER will be reserved as follows as of column 81:
......column 81 column 123 .............| | .............UPCUSER0_____________OFF_____N______________ .............8________0_______0__UPCLT#T0_______. .............| | .....column 124 column 160 is next line X'15'
For an explanation of the meaning of the contents, see also "Output from KDCINF (examples)":
UPCUSER (value of USER):
Name of the user ID.OFF (value of STATUS):
The user ID is disabled.N (value of OSERV):
The user ID is not processing any service at present.8 (value of NR.TACS):
Eight transaction jobs have so far been entered under this user ID.0 (value of SECCNT):
Number of security violations under this user ID.UPCLT#T0 (value of LTERM):
Name of the LTERM partner via which the user ID signs on.
SHOW-CONFIGURATION
SHOW-CONFIGURATION allows you to display the values defined by the last CREATE-CONFIGURATION or MODIFY-CONFIGURATION statement.
SHOW-CONFIGURATION | Alias: SHOWATTR |
CONFIGURATION-ID = 1 / <integer_1..1> ,OUTPUT = *SYSOUT /*LOGGING-FILE | |
CONFIGURATION-ID = 1 | ||
Identifies the configuration. The only permissible value is 1. | ||
OUTPUT= | ||
Specifies the destination to which the requested data is to be output. | ||
*SYSOUT | ||
The requested data is to be output to SYSOUT. | ||
*LOGGING-FILE | ||
The requested data is to be written to the log file (see CREATE-CONFIGURATION; operand WRITE-LOGGING-FILE). If no log file was defined with CREATE-CONFIGURATION or MODIFY-CONFIGURATION, the data output will be rerouted to SYSOUT. | ||
Example
-> //SHOW-CONF OUTPUT=*SYSOUT
<- -- current configuration data: ---------------------------------
local name = UPCPT#T0
symbolic destination name = DBSADMT0
partner name (from upicfile) = DBSUPAT0
program name is enabled to UPIC
no user identification given
logging file name = LOG.CALLUTM
open mode = replace
record length = 79
logging info = transmitted and received messages
file is open
upic trace is switched off
program monitoring job variable is not specified
encryption is not available
-- end configuration data --------------------------------------
->