The APRO call (address program) enables you to address a job-receiving service or a TAC queue in the job-submitting service. The APRO call is only applicable with distributed processing with UTM-D. Data is sent to the job-receiving service using either MPUT or FPUT/DPUT. In these calls the receiver is specified by means of the service identifier defined in the APRO call.
Setting the 1st parameter (KDCS parameter area)
The following table shows the various options and the necessary entries in the KDCS parameter area.
Function of the call | Entries in the KDCS parameter area | ||||||
|---|---|---|---|---|---|---|---|
KCOP | KCO M | KCLM | KCRN | KCPA | KCPI | KCOF | |
Address a dialog service | "APRO" | "DM" | 0/19/58 | LTAC name | (OSI-)LPAP name / Master-LPAP name / blanks | service ID | Permitted OSI function |
Address an asynchronous service or a TAC queue | "APRO" | "AM" | 0/19/58 | LTAC name | (OSI-)LPAP name / Master-LPAP name / blanks | service ID | Permitted OSI function |
The entry in the KCPA field depends on the type of addressing involved:
for single-step addressing the field must contain blanks
for double-step addressing the field must contain the name of the partner application ((OSI-)LPAP name or Master-LPAP name).
Further information on single and double-step addressing of job-receiving service with distributed processing can be found in the openUTM manual “Concepts and Functions”.
Setting the 2nd parameter (selecting special OSI TP function combinations)
The second parameter area is only used for communication via the OSI TP protocol. It allows you to specify function combinations other than those available via the standard selection using the KDCS KOCF parameters. It also allows you to select whether SIGNON data should be transferred to the job-receiving service. A language-specific data structure is available for the second parameter area: for COBOL in the KCAPROC COPY element, for C/C++ in the kcapro.h include file.
If the second parameter area is used, you must specify the values 19 or 58 in the field KCLM for the length of the data structure and the field KCDF must contain the value "O".
Setting the parameters in the KDCS parameter area | |
Field name in the KDCS parameter area | Contents |
"APRO" | |
"DM"/"AM" | |
0/19/58 | |
LTAC name | |
(OSI-)LPAP name / Master-LPAP name / blanks | |
service ID | |
OSI functions | |
Setting the parameters in the second parameter area (only for KCOF=O) | |
Field name in the 2nd parameter area | Contents |
Version number of data structure | |
Polarized FU (Y) | |
Handshake FU (Y/N) | |
Commit FU (Y/N) | |
Chained FU (Y/blanks) | |
KCFUFILL | empty - for future extensions |
Security type (N/S/P) | |
Data type of user ID (P/T/O) | |
Length of user ID | |
User ID | |
KCSECFIL | empty - for future extensions |
Data type of the password (P/T/O) | |
Length of the password | |
Password | |
KDCS call | |
KDCS parameter area | Second parameter area |
C/C++ macro calls | |
Parameters | |
KDCS_APRODM / KDCS_APROAM | (kcrn,kcpa,kcpi) |
KDCS_APRODM_OSI / KDCS_APROAM_OSI | (kcrn,kcpa,kcpi,kcof) |
KDCS_APRODM_OSI_O / KDCS_APROAM_OSI_O | (nb,kclm,kcrn,kcpa,kcpi) |
openUTM return information | |
|---|---|
Field name in the KB return area | Contents |
Return code | |
Internal return code | |
You can enter the following information for the APRO call in the KDCS parameter area:
KCOP
In the KCOP field, enter the APRO operation code.
KCOM
In the KCOM field, enter the operation modifier:
DM (Dialog message) for addressing a dialog service
AM (asynchronous message) for addressing an asynchronous service or a TAC queue.
KCLM
In the KCLM field, enter the length of the 2nd parameter area:
length zero, if no second parameter area is used
length 19, if a second parameter area is used and the “N" or “S" security type is selected
length 58, if a second parameter area is used and “P" security type is selected.
KCRN
In the KCRN field, enter the logical transaction code (LTAC name) of the job-submitting service.
KCPA
In the KCPA field, you may have to identify a partner application depending on the type of addressing:
enter the logical name of the partner application in the case of double-step addressing, i.e. the LPAP name, OSI-LPAP name or master LPAP name of an OSI-LPAP or LU6.1-LPAP bundle.
enter blanks for single-step addressing (the name of the partner application is in this case taken from the generation statement LTAC).
The partner application entry in KCPA has priority over the partner application specified in the LTAC statement at generation.
KCPI
In the KCPI field, assign the service ID to be used by the job-submitting service in the MPUT, MCOM, FPUT, DPUT or MGET calls to address the job-receiving service. The service ID must begin with the character ">".
KCOF
The KCOF field contains the functions permitted for communication with an OSI TP partner (irrelevant for communication via LU6.1 protocol).
Possible values:
B (basic functions)
Basic functionsH (handshake functions)
Basic and handshake functions (only possible with APRO DM)C (chained transactions)
Basic and commit functions with chained transactionsO (other combination)
The functions are selected via the second parameter area, i.e. if KCOF=O is specified, a second parameter area must be passed during the KDCS call.
You specify the following in the second parameter area:
KCVERS
In the KCVERS field, enter the version number of the data structure: this is 1 in this openUTM version.
KCFUPOL
In the KCFUPOL field, specify whether the “polarized control" functional unit should be selected. Since “shared control" is not supported in this version, the only permitted entry is “Y“.
KCFUHSH
In the KCFUHSH field, specify whether the “Handshake" functional unit should be selected (Y/N).
If an asynchronous service is addressed (APRO AM), then "N" must be specified for KCFUHSH.
KCFUCOM
In the KCFUCOM field, specify whether the "Commit" functional unit should be selected (Y/N). The "Commit" functional unit can only be selected if the addressed OSI-LPAP partner contains the abstract syntax CCR in the application context (Commitment, Concurrency and Recovery).
KCFUCHN
In the KCFUCHN field, specify whether the "Chained Transactions" functional unit should be selected. This field is only relevant if the "Commit" functional unit has also been selected, i.e. if KCFUCOM=Y is set.
Since "Unchained Transactions" are not supported in this version, the only permitted entry here is “Y” if the "Commit" functional unit was selected.
If the "Commit" functional unit was not selected, the KCFUCHN field is irrelevant. In this case, enter a blank.
KCSECTYP
In the KCSECTYP field, enter the security type.
The security type controls whether SIGNON data (user ID and password) is transferred to the job-receiving service:
N (none)
No SIGNON data is transferred to the job-receiving service.S(same)
The user ID under which the local service runs, is transferred to the job-receiving service.P(program)
The values specified in the KCUSERID and KCPSWORD fields are transferred to the job-receiving service as the user ID and password.
You can only select the security types "S" or "P", if the addressed OSI-LPAP partner in the application context contains the abstract syntax UTMSEC.
KCUIDTYP
In the KCUIDTYP field, you enter the data type of the user ID specified in the KCUSERID field:
P: The string entered in KCUSERID is a "printable string" type.
T: The string entered in KCUSERID is a "T61 string" type.
O: The string entered in KCUSERID is an "octet string" type.
An octet string is a hexadecimal string. No code conversion is performed
For the range of values for these data types refer to the openUTM manual “Generating Applications”, KDCDEF statement LTAC.
KCUIDLTH
In the KCUIDLTH field, you enter the length of the user ID specified in the KCUSERID field (in bytes, 16 maximum).
KCUSERID
In the KCUSERID field, you specify the user ID which, if KCSECTYP=P is set, will be transferred to the job-receiving service.
KCPWDTYP
In the KCPWDTYP field, you enter the data type of the password specified in the KCPSWORD field:
P: The string entered in KCPSWORD is a "printable string" type.
T: The string entered in KCPSWORD is a "T61 string" type.
O: The string entered in KCPSWORD is an "octet string" type (see also the field "KCUIDTYP")
For the range of values for these data types refer to the openUTM manual “Generating Applications”, KDCDEF statement LTAC.
KCPWDLTH
In the KCPWDLTH field, you enter the length of the password specified in the KCPSWORD field (in bytes, 16 maximum).If no password is to be transferred, enter zero.
KCPSWORD
In the KCPSWORD field, you enter the password which, if KCSECTYP=P is set, will be transferred to the job-receiving service.
For the KDCS call you enter:
1st parameter
The address of the KDCS parameter area.
2nd parameter
(if required): the address of the second parameter area (selection of special OSI TP function combinations).
Macro names
The use of C/C++ calls is described in detail in section "C/C++ macro interface".
openUTM returns:
KCRCCC
in the KCRCCC field: the KDCS return code, see next page.
KCRCDC
in the KCRCDC field: the internal return code of openUTM (see the openUTM manual ”Messages, Debugging and Diagnostics”).
KDCS return codes in the KCRCCC field for the APRO call
The following codes can be analyzed in the program:
000 | Function carried out. |
40Z | UTM cannot perform the function. There is a generation error or a system error, or the APRO function was called although the application was generated without distributed processing, or no connection to the partner application possible at the moment (see value of KCRCDC). |
41Z | Impermissible APRO call. This can be, for example, for one of the following reasons:
|
42Z | Entry in KCOM invalid |
43Z | Entry in KCLM invalid. |
44Z | Value in KCRN does not identify a valid LTAC of a job-receiving service.
|
46Z | Entry in KCPA invalid, i.e. no partner application is generated under the specified name, or blanks were entered in KCPA and there is no application name defined in the LTAC generation statement. |
47Z | KCOF=O was specified. However the 2nd parameter area is missing or invalid. |
48Z | Invalid data structure version. |
55Z | Entry in KCPI invalid (does not begin with ">"), or service ID already assigned by job-submitting service. |
58Z | Value in KCOF invalid |
Additional error codes can be found in the dump:
71Z | INIT call missing or was given the form DM in the MSGTAC program. |
| 89Z | When addressing an OSI TP job receiver, unused fields of the KDCS parameter area were not specified binary zero. |
Features of the APRO call
A service which communicates with a partner application via OSI TP protocol using the "Commit" functional unit cannot communicate with another partner application via LU6.1.
If the OSI TP protocol is used in a service which takes part in a distributed transaction part, all job receivers must be allocated to the same local ACCESS-POINT and, if necessary, this ACCESS-POINT must be identical to the ACCESS-POINT used for the communication with a job-submitting service.
Security types P and S can be selected both with APRO DM and with APRO AM. In the case of dialog services, the job submitter is signed on by means of the transferred user ID when the service is started and signed off again when it terminates. In the case of asynchronous services, the transferred user ID remains active only until the job has been entered in the appropriate queue.
For dialog services, the job submitter is rejected when there is already an OSI TP dialog service running under this name, when a user is logged on through an LTERM partner and it is prohibited for users to sign on to the application more than once (SIGNON statement, MULTI-SIGNON=NO) or when the user ID has been configured with RESTART=YES and the functional unit commit has not been selected.
The job submitter can always sign on under the user ID passed in order to be able to place a job in a queue for asynchronous services.If security type "S" is selected, openUTM transfers the user ID under which the local service is running, to the job-receiving service. It is assumed that T61 String is used.
If security type "P" is selected in the 2nd parameter area, you must specify user ID and password. Additionally, the data type of user ID and password must also be specified. Possible data types are Printable String, T61 String and Octet String. For the range of values for these data types, refer to the openUTM manual “Generating Applications”, KDCDEF statement LTAC.
Note for BS2000 systems
If Octet String is specified, no code conversion is performed. The Octet String type is necessary when you transfer passwords which were generated in Hex-String (PASSWORD=X'aabbcc..') format.
A successful APRO DM call means that a virtual connection has been established with the partner application.
A successful APRO call does not mean that it is possible to exchange messages with the job-receiving service. A session or association is not reserved until the end of the program unit run in which the first message was sent to the job-receiving service.
If at the time of the APRO call no connection to the remote application has been established, UTM initiates the connection setup.
If openUTM returns a KDCS error code
!=000 as a result of an APRO DM call no message should be sent with MPUT to the job receiver, because the service would then be aborted with KCRCCC=74Z.A message has to be sent to a job-receiving service addressed by APRO DM in the same transaction, otherwise openUTM aborts the service with KCRCCC=87Z at PEND.
An asynchronous job must be associated with an asynchronous service addressed by APRO AM before the next PEND call, otherwise openUTM aborts the service with 86Z at PEND.
A RSET call only rolls back the address of a dialog service if the APRO DM occurred in the same processing step, i.e. no dialog message has as yet been sent to the job-receiving service (MPUT with following PEND/PGWT).
If multiple job-submitting services exist simultaneously in one application, these may use identical service identifiers. These may also be used for addressing differing job-receiving services.
If a job complex is to be sent to the remote application, the APRO AM call must precede the MCOM BC call and the service identifier for the MCOM BC call must be entered in the KCRN field.
Life of a service ID
A service ID created with APRO DM is relevant for transaction security, i.e. it forms part of transaction-logged security. It is present until the job-receiving service is terminated and is not released until the end of the transaction in which the job submitter has read the message from the job receiver.
A service identifier created by APRO AM is released
after a successful FPUT/DPUT NE call,
at the next RSET or PEND call,
after 40Z has been returned by an FPUT/DPUT call, or
with job complexes with that service identifier: following an MCOM EC call or after 40Z has been returned by an MCOM BC or DPUT call.
Once a service ID has been released, it can be used for the next job receiver/submitter relationship.
Addressing a Master LPAP
If a master LPAP is addressed with the APRO call, a slave LPAP from the LPAP bundle is selected if this is the first APRO call of the current transaction for this master LPAP.
With an APRO DM call, the first slave LPAP is selected to which a logical connection has been established. If no logical connection has been established to any slave LPAP, the return value is 40Z/KD10.
With an APRO AM call, the first slave LPAP is selected to which a logical connection has been established. If no logical connection has been established to any slave LPAP, one of the slave LPAPs is selected.
For every slave LPAP checked during selection, and to which no association or session is established, establishment of an association or session is initiated.
If a slave LPAP has been selected, the same slave LPAP is used for every additional APRO call in this transaction addressed to the master LPAP.
A subsequent APRO DM call can return 40Z/KD10 if the first APRO call was APRO AM and no association or session had previously been established to any of the slave LPAPs or if the logical connection has been cleared again in the interim.