gtpg2m0w | General Macros |
Use this general macro to provide the communication interface between the control operator and the TPF application programs that are written to connect to remote nodes using the TPF/APPC session interface using LU 6.2 protocols.
This section contains a description of the CNOSC macro in its general form, followed by a separate section for each of the valid verbs.
Format
|
Each macro call begins with CNOSC, followed by the positional parameter verbname, which specifies the verb to be executed. This is followed by one or more keyword parameters and values for those parameters. The values specify either a keyword option or a main storage location of a field.
The main storage location of a field can be specified as either the symbolic name of the field or as a register that points to the field. If you specify a register, the register name must be enclosed in parentheses and must be in the range of R1-R7.
Throughout the descriptions of the CNOSC macros, the phrase source LU refers to the TPF LU and the target LU refers to the remote LU.
Table 2 is a summary of the supported verb names and their associated parameters. The table also contains:
More detailed information for each parameter is provided in the individual
verb descriptions later in this chapter.
Table 2. TPF/APPC Change Number of Session Verbs and Valid Keywords
Verb Name | Keyword Parameter | Passed or Returned | Description | Architecture Equivalent |
---|---|---|---|---|
CHANGE | LUNAME | Passed | This specifies the name of the remote partner LU. | LU_NAME |
MODE | Passed | This specifies the mode name for which the session limit and polarities are to be changed. | MODE_NAME | |
LIMIT | Passed | This specifies the maximum number of sessions to be allowed between the source (TPF) LU and the target (remote) LU for the specified mode name. | LU_MODE_SESSION_LIMIT | |
CONW | Passed | This specifies the minimum number of sessions of which the source LU is designated to be the contention winner. | MIN_CONWINNERS_SOURCE | |
CONL | Passed | This specifies the minimum number of sessions of which the target LU is designated to be the contention winner. (Or the minimum number of sessions of which the source LU is designated to be the contention loser.) | MIN_CONWINNERS_TARGET | |
RESP | Passed | This specifies which LU is responsible for selecting and deactivating sessions as a result of a change that decreases the session limit. | RESPONSIBLE | |
RCODE | Returned | This specifies where the return code is to be returned. | RETURN_CODE | |
DISPLAY | LUNAME | Passed | This specifies the name of the remote partner LU. | FULLY_QUALIFIED_LU_NAME |
MODE | Passed | This specifies the mode name for which the session limit and polarities are to be displayed. | MODE_NAME | |
LIMIT | Returned | This specifies the maximum number of sessions to be allowed between the source (TPF) LU and the target (remote) LU for the specified mode name. | LU_MODE_SESSION_LIMIT | |
CONW | Returned | This specifies the minimum number of sessions of which the source LU is designated to be the contention winner. | MIN_CONWINNERS | |
CONL | Returned | This specifies the minimum number of sessions of which the target LU is designated to be the contention winner. (Or the minimum number of sessions of which the source LU is designated to be the contention loser.) | MIN_CONLOSERS | |
RESP | Returned | This specifies which LU is responsible for selecting and deactivating sessions as a result of a change that decreases the session limit. | related to TERMINATION_COUNT | |
DRAIN | Returned | This specifies whether the source LU or the target LU or both can drain its allocation requests. |
DRAIN_LOCAL_LU DRAIN_REMOTE_LU | |
RCODE | Returned | This specifies where the return code is to be returned. | RETURN_CODE | |
INITIALIZE | LUNAME | Passed | This specifies the name of the remote partner LU. | LU_NAME |
MODE | Passed | This specifies the mode name for which the session limit and polarities are to be initialized. | MODE_NAME | |
LIMIT | Passed | This specifies the maximum number of sessions to be allowed between the source (TPF) LU and the target (remote) LU for the specified mode name. | LU_MODE_SESSION_LIMIT | |
LOCAL | Passed | This specifies the local TPF/APPC LU. | Not applicable | |
CONW | Passed | This specifies the minimum number of sessions of which the source LU is designated to be the contention winner. | MIN_CONWINNERS_SOURCE | |
CONL | Passed | This specifies the minimum number of sessions of which the target LU is designated to be the contention winner. (Or the minimum number of sessions of which the source LU is designated to be the contention loser.) | MIN_CONWINNERS_TARGET | |
CDRM | Passed | This specifies the name of the remote cross-domain resource manager (CDRM) that owns the specified remote LU. | Not applicable | |
CP | Passed | This specifies the control point (CP) name of the adjacent APPN node where the specified remote LU resides. | Not applicable | |
RCODE | Returned | This specifies where the return code is to be returned. | RETURN_CODE | |
RESET | LUNAME | Passed | This specifies the name of the remote partner LU. | LU_NAME |
MODE | Passed | This specifies the mode name for which the session limit and polarities are to be reset. | MODE_NAME | |
RESP | Passed | This specifies which LU is responsible for selecting and deactivating sessions. | RESPONSIBLE | |
DRAIN | Passed | This specifies whether the source LU or the target LU or both can drain its allocation requests. | DRAIN_SOURCE | |
FORCE | Passed | This specifies whether the source LU is to force the resetting of its session limit when certain error conditions occur that prevent successful exchange of the CNOS request and reply. | FORCE | |
RCODE | Returned | This specifies where the return code is to be returned. | RETURN_CODE | |
|
Table 3 contains a list of all the primary return codes and their
meanings, and Table 4 contains a list of all the secondary return codes and their
meanings. Not all return codes are possible for every verb. The
individual CNOSC macro descriptions document the valid return codes for that
CNOSC macro. In addition, Table 5 and Table 6 show the correlation between the return
codes and the verbs for which they are valid. The symbolic names of the
return code values are defined in data macro ICN0OS.
Table 3. CNOSC Primary Return Codes
Symbolic Name | Hex Value | Meaning |
---|---|---|
CNOSRC_OK | 0000 | The function completed successfully. Check the secondary return code for additional information. |
CNOSRC_PARAMETER_ERROR | 0004 | An invalid parameter was detected. Check the secondary return code. |
CNOSRC_ALLOC_ERROR | 0008 | An allocation error occurred. Check the secondary return code. |
CNOSRC_RACE_REJECT | 000C | The CNOSC verb request failed because the source LU or target LU is currently processing another CNOS transaction for the same mode name. The source and target LU's CNOS parameters are not changed, and the other CNOS transaction is processed to completion. |
CNOSRC_LIMIT_ZERO | 0010 | The program attempted to change a session limit that was not initialized; that is, the session limit is 0. |
CNOSRC_RESOURCE_FAILURE | 0014 | A resource failure occurred. Check the secondary return code for additional information. |
CNOSRC_LIMIT_CLOSED | 0018 | The target LU will not currently allow the session limit for the specified mode name to be raised above zero. This condition is not necessarily permanent; retry the CNOS request later. |
CNOSRC_LIMIT_NOT_ZERO | 001C | The program attempted to initialize a session limit that is already initialized; that is, the session limit is already greater than zero. |
CNOSRC_INVALID_REQ | 0020 | The request was invalid and failed. Check the secondary return code for more information. |
CNOSRC_LOCAL_LU_MISMATCH | 0024 | The CNOSC INIT request was rejected because the local LU specified cannot
be used.
|
Table 4. CNOS Secondary Return Codes
Symbolic Name | Hex Value | Meaning |
---|---|---|
CNOSRC_AS_SPECIFIED | 00000000 | The request is complete as specified. |
CNOSRC_AS_NEGOTIATED | 00000004 | The request is complete but was negotiated by the target LU. |
CNOSRC_FORCED | 00000008 | The RESET request could not be completed normally, so the force was done as specified. |
CNOSRC_RETRY_LATER | 0000000C | The request failed. Retry the request later. |
CNOSRC_NO_RETRY | 00000010 | The request failed. Do not retry the request. |
CNOSRC_INVALID_LU | 00000014 | A parameter check was detected. The remote LU specified on the LUNAME parameter is invalid. |
CNOSRC_INVALID_MODE | 00000018 | A parameter check was detected. An invalid mode name was
passed. This error occurs if:
|
CNOSRC_NON_ZERO_LIMIT_REQ | 0000001C | A parameter check was detected. A session limit of zero was passed and a nonzero limit is required. |
CNOSRC_SNASVCMG_INVALID | 00000020 | A parameter check was detected. The mode name SNASVCMG is not allowed for the CHANGE verb. |
CNOSRC_SUM_ERROR | 00000024 | A parameter check was detected. The sum of CONW and CONL exceeds the specified session limit. |
CNOSRC_ZERO_LIMITS_REQ | 00000028 | A parameter check was detected. All session limits must be zero before SNASVCMG can be reset. |
CNOSRC_ALREADY_RESET | 0000002C | A parameter check was detected. One cause for this is that a RESET request was issued to allow draining for the source LU; however, a previous RESET request disallowed draining for the source. Another cause is that a RESET MODE=ALL was issued but all mode names (other than SNASVCMG) were already reset. |
CNOSRC_INVALID_STATE | 00000030 | The specified request cannot be completed while the system is below CRAS state. |
CNOSRC_SINGLE_INVALID | 00000038 | An invalid request was detected. The single session mode name is not allowed for the CHANGE verb. |
CNOSRC_LOCAL_LU_INVALID | 0000003C | A parameter check was detected. The local LU specified on the LOCAL parameter is invalid. |
CNOSRC_INVALID_CDRM | 00000040 | A parameter check. An invalid CDRM name was passed. |
CNOSRC_CDRM_NOT_ACTIVE | 00000044 | A parameter check. There is no CDRM-CDRM session with the specified remote CDRM. |
CNOSRC_MAX_SESSION_EXCEED | 00000054 | A parameter check. The value specified for the session limit is greater than the maximum number of sessions permitted. |
CNOSRC_HOST_VIOLATION | 00000060 | A resource failure. Sessions exist for this LU on another processor. |
CNOSRC_LOCAL_NOT_ACTIVE | 00000064 | A resource failure. The specified (or default) local LU is not active. |
CNOSRC_CP_NOT_VALID | 00000068 | A parameter check. The CP name passed was not valid. |
CNOSRC_CP_NOT_ACTIVE | 0000006C | A resource failure. No active ALS exists between the TPF system and specified adjacent CP. |
Table 5. Correlation of Primary Return Codes to CNOSC Verbs
Primary Return Code (Value) | Verb | |||
---|---|---|---|---|
CHANGE | DISPLAY | INITIALIZE | RESET | |
OK (0) | S | X | S | S |
PARAMETER ERROR (4) | S | S | S | S |
ALLOC ERROR (8) | S | S | S | |
RACE REJECT (C) | X | X | X | |
LIMIT ZERO (10) | X | |||
RESOURCE FAILURE (14) | S | S | S | |
LIMIT CLOSED (18) | X |
| ||
LIMIT NOT ZERO (1C) | X | |||
INVALID REQ (20) | S | X | S | S |
LOCAL LU MISMATCH (24) |
|
| X |
|
|
Table 6. Correlation of Secondary Return Codes to CNOSC Verbs
Secondary Return Code (Value) | Verb | Corresponding Primary Return Code Value | |||
---|---|---|---|---|---|
CHANGE | DISPLAY | INITIALIZE | RESET | ||
AS SPECIFIED (0) | X | X | X | (0) | |
AS NEGOTIATED (4) | X | X | X | (0) | |
FORCED (8) | X | (0) | |||
RETRY LATER (C) | X | X | X | (8) | |
NO RETRY (10) | X | X | X | (8), (14), (18) | |
INVALID LU (14) | X | X | X | X | (4) |
INVALID MODE (18) | X | X | X | X | (4) |
NON ZERO LIMIT REQ (1C) | X | X | (4) | ||
SNASVCMG INVALID (20) | X | (4) | |||
SUM ERROR (24) | X | X | (4) | ||
ZERO LIMITS REQ (28) | X | (4) | |||
ALREADY RESET (2C) | X | (20) | |||
INVALID STATE (30) | X | X | X | X | (20) |
SINGLE INVALID (38) | X | X | X | X | (20) |
LOCAL LU INVALID (3C) |
|
| X |
| (4) |
INVALID CDRM (40) | X | (4) | |||
CDRM NOT ACTIVE (44) | X | (4) | |||
MAX SESSION EXCEED (54) | X | X | (4) | ||
HOST VIOLATION (60) | X | (14) | |||
LOCAL NOT ACTIVE (64) | X | X | X | (14) | |
CP NOT VALID (68) | X | (4) | |||
CP NOT ACTIVE (6C) | X | (4) |
Examples