APING

APING allows a management application to ping a remote LU in the network. A verification data string (of specified length) can be appended to the end of the VCB and returned when the partner_ver_len field is set to a value greater than zero.

Personal Communications or Communications Server APING is implemented as an internal service transaction program, which uses the Personal Communications or Communications Server APPC API (described in Personal Communications Client/Server Communications Programming).

VCB Structure

typedef struct aping
{
   unsigned short  opcode;            /* verb operation code           */
   unsigned char   reserv2;           /* reserved                      */
   unsigned char   format;            /* format                        */
   unsigned short  primary_rc;        /* primary return code           */
   unsigned long   secondary_rc;      /* secondary return code         */
   unsigned char   lu_name[8];        /* local LU name                 */
   unsigned char   lu_alias[8];       /* local LU alias                */
   unsigned long   sense_data;        /* sense data                    */
   unsigned char   plu_alias[8];      /* partner LU alias              */
   unsigned char   mode_name[8];      /* mode name                     */
   unsigned char   tp_name[64];       /* destination TP name           */
   unsigned char   security;          /* security level                */
   unsigned char   reserv3a[3];       /* reserved                      */
   unsigned char   pwd[10];           /* password                      */
   unsigned char   user_id[10];       /* user ID                       */
   unsigned short  dlen;              /* length of data to send        */
   unsigned short  consec;            /* number of consecutive sends   */
   unsigned char   fqplu_name[17];    /* fully qualified partner       */
                                      /* LU name                       */
   unsigned char   echo;              /* data echo flag                */
   unsigned short  iterations;        /* number of iterations          */
   unsigned long   alloc_time;        /* time taken for ALLOCATE       */
   unsigned long   min_time;          /* min send/receive time         */
   unsigned long   avg_time;          /* average send/receive time     */
   unsigned long   max_time;          /* max send/receive time         */
   unsigned short  partner_ver_len;   /* size of string to receive     */
} APING;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_APING
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
lu_name
LU name of the local LU from which the APING verb is sent. This name is an 8-byte type-A EBCDIC character string. If this field is set to all zeros, the lu_alias field will be used for determining the local LU.
lu_alias
Alias for the local LU from which the APING verb is sent. This is an 8-byte string in a locally displayable character set. This field is only significant if the lu_name field is set to all zeros, in which case all 8 bytes are significant and must be set. If both the lu_name and the lu_alias are set to binary zeros then the default (control point) LU is used.
plu_alias
Alias by which the partner LU is known to the local transaction program. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. This name must match the name of a partner LU established during configuration. If this parameter is set to binary zeros, the fqplu_name parameter is used instead.
mode_name
Name of the mode to be used. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
tp_name
Name of the invoked transaction program. This is a 64-byte string. The Node Operator Facility does not check the character set of this string. The value of tp_name must match that configured on the remote LU. The string is usually set to APINGD in EBCDIC padded to the right with EBCDIC spaces.
security
Specifies the information the partner LU requires in order to validate access to the invoked transaction program:

AP_NONE
AP_PGM
AP_SAME
AP_PGM_STRONG

pwd
Password associated with user_id. This is a 10-byte type-AE EBCDIC character string, padded to the right with EBCDIC spaces. Only needed if security is set to AP_PGM or AP_PGM_STRONG.
user_id
User ID required to access the partner transaction program. This is a 10-byte type-AE EBCDIC character string, padded to the right with EBCDIC spaces. Needed if security is set to AP_PGM, AP_PGM_STRONG or AP_SAME.
dlen
Length of data to be sent by APING transaction program. APING sends a string of zeros, of length dlen.
consec
Number of consecutive sends performed during each iteration. APING issues this number of MC_SEND_DATA verbs, each consisting of dlen bytes of data. If the echo parameter is set to AP_YES, APING marks the last MC_SEND_DATA as AP_SEND_DATA_P_TO_R_FLUSH (Prepare to Receive Flush) and awaits a response containing data from the partner APINGD transaction program (by issuing a MC_RECEIVE_AND_WAIT). If the echo parameter is set to AP_NO, APING flushes the data and awaits a confirm (by marking the last MC_SEND_DATA as AP_SEND_DATA_CONFIRM). In either case, the sequence described here corresponds to an SNA chain.
fqplu_name
This is a 17-byte fully qualified network name for the partner LU. This name is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This field is only significant if the plu_alias field is set to all zeros.
echo
Specifies whether the APING transaction program expects a response when it has completed sending the required amount of data:

AP_YES
AP_NO

iterations
Number of iterations of consecutive sequences (defined by the consec parameter) issued by APING. In SNA terms, this parameter defines the number of chains that will be sent.
partner_ver_len
Maximum length of the partner transaction program verification data string that can be received by the management application.

Returned Parameters

If the verb executes successfully, APING returns the following parameters:
primary_rc
AP_OK
sense_data
This will be zero if the verb has returned successfully.
alloc_time
Time required (in milliseconds) for the MC_ALLOCATE to the remote transaction program to complete.
min_time
Minimum time (in milliseconds) required for a data-sending iteration. This parameter includes the time required for the partner to respond (either by sending data or issuing a confirm, depending on the setting of the echo parameter).
avg_time
Average time (in milliseconds) required for a data-sending iteration. This parameter includes the time required for the partner to respond (either by sending data or issuing a confirm, depending on the setting of the echo parameter).
max_time
Maximum time (in milliseconds) required for a data-sending iteration. This parameter includes the time required for the partner to respond (either by sending data or issuing a confirm, depending on the setting of the echo parameter).
partner_ver_len
Length of verification string returned by the partner transaction program. The string itself is appended to the end of the VCB.
If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_LU_NAME

AP_INVALID_LU_ALIAS

APING uses the MC_ALLOCATE, MC_SEND_DATA, MC_RECEIVE_AND_WAIT, MC_CONFIRM, and MC_DEALLOCATE verbs provided by the Personal Communications or Communications Server APPC API. The parameters returned by these verbs in the case of unsuccessful execution are documented in Personal Communications Client/Server Communications Programming.

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:
primary_rc
AP_NODE_NOT_STARTED
If the verb does not execute because the node is stopping, the Program returns the following parameter:
primary_rc
AP_NODE_STOPPING
If the verb does not execute because of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR