Debugging of User-Defined Communications Applications

This section is intended to help you debug your user-defined communications applications. It contains information about:

System services and tools
Error codes reported to the application program and QSYSOPR operation
Common error list

System Services and Tools

There are several tools on the iSeries^(TM) server you can use to debug your user-defined communications application. Some of the system provided tools that are useful for developing user-defined communications applications include the following CL commands:

Program Debug (STRDBG)
Work with Job, Work with Communications Status (WRKJOB OPTION(*CMNSTS))
Work with Job, Display Job Log (WRKJOB OPTION(*JOBLOG))
Display Connection Status (DSPCNNSTS)
Display Inbound Routing Data (press F6 (Display inbound routing information) following the DSPCNNSTS command)
Check Communications Trace (CHKCMNTRC)
Delete Communications Trace (DLTCMNTRC)
End Communications Trace (ENDCMNTRC)
Print Communications Trace (PRTCMNTRC)
Start Communications Trace (STRCMNTRC)
Start System Service Tools (STRSST)
- Work with communications trace
- Work with error log
Dump System Object (DMPSYSOBJ)

Program Debug

Program debug (STRDBG) allows you to trace the program and variables, set stops, change variables, and display variables. You can use this function to verify that the parameters are passed correctly.

Work with Communications Status

The Work with Job command, Work with Communications Status option, (WRKJOB OPTION(*CMNSTS)) shows the enabled links and operation counts for each link. It also reports information such as the communications handle the last operation requested, and the total input, output, and other operations requested. This information is shown for every link enabled by the job.

Display Job Log

The Work with Job command, selecting the Display job log option (WRKJOB OPTION(*JOBLOG)) allows you to view the messages in the job log that help determine the exact cause of the problem.

Display Connection Status

The Display Connection Status (DSPCNNSTS) command shows information about the switched virtual circuits (SVCs) and permanent virtual circuits (PVCs) that are in use by the application using the device description.

Note: The Display Line Description (DSPLIND) command also shows for each line, the SVCs that are in use, available, or attached to a controller description. This is not true for PVCs.

Display Inbound Routing Information

Pressing F6 (Display inbound routing information) when the Display Connection Status display is shown (DSPCNNSTS command) shows the results of the calls to the Set Filter (QOLSETF) API. It also helps to determine which device description has set a filter with duplicate inbound routing information.

Work with Communications Trace

Using the communications trace function you can obtain information about a communications line. You can access the communications trace function through the following CL commands:

Check Communications Trace (CHKCMNTRC)
Delete Communications Trace (DLTCMNTRC)
End Communications Trace (ENDCMNTRC)
Print Communications Trace (PRTCMNTRC)
Start Communications Trace (STRCMNTRC)

For more information on using the communications trace CL commands, see the Communications Management Link to PDF book.

You can also access the communications trace function through the system service tools. You can use this function by entering the Start System Service Tools (STRSST) command and selecting the option to start a service tool.

Using the option to Work with communications trace shows data just as it appears to the network. If the application requests that data be sent and the request does not appear in the communications trace, the request is rejected. The return and reason codes, and the error code reported in the parameter list for the Send Data (QOLSEND) API indicates the reason the request was rejected.

Work with Error Log

The error log utility is part of the system service tools. You can use it by entering the Start System Service Tools (STRSST) command and selecting the option to start a service tool.

Some communications errors are reported by the system to the error log. A remote application that is communicating with a user-defined communications application on the local system, could cause an entry to be generated in the error log if one of the following conditions are met:

When using a LAN, data is not received by the application and exceeds internal threshold values (3 MB).
When using an X.25 network, data is not received by the application and exceeds internal threshold values (128KB).

For both cases, the associated message in QSYSOPR identifies the error log that contains the error log entry. The error log entry contains information only.

Dump System Object to View User Spaces

The Dump System Object (DMPSYSOBJ) command is used to inspect the user spaces after they are filled in by your application. The following examples indicate what the user spaces look like for some of the operations.

User Space to Set a Filter to Route Inbound Data

This user space is filled in to activate two X.25 filters which will route any X.25 call containing X'BB', or X'DD' in the first byte of call user data (protocol ID byte).

Figure 1-1. User Space to Set a Filter to Route Incoming X.25 Calls

5738SS1 V2R1M0  910524       i5/OS DUMP       006625/QSECOFR/QPADEV0001  12/21/90 12:42:07  PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- OUTBUFFER                       CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        OUTBUFFER                       TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:40:03              SIZE-          00002200
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       00A00A00   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934D6E4 E3C2E4C6   C6C5D940 40404040 40404040 40404040  *  -  OUTBUFFER    *
  000020   40404040 40404040 E0000000 00000000   00002000 00800000 00000000 00000000  *   \              *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *      (a          *
SPACE-
  000000   01000002 001001BB 00000000 00000000   00000000 000001DD 00000000 00000000  *    Y       t     *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                  *
        LINES  000040    TO    001FFF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F1D8E2 C5C3D6C6   D9404040 F0F0F6F6 F2F5    *QPADEV0001QSECOFR   006625   *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *          1       *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F4F0 F0F44040  *V2R1M00901221124004 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                  *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                  *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                  *
  0000A0   00000000 00000000                                                          *                  *
END OF DUMP
        * * * * *  E N D  O F  L I S T I N G  * * * * *

User Space for X'B000' Operation, Initiating an SVC Call

The user space below has been filled in to initiate an SVC call specifying the following:

Default packet and window sizes
D-bit (not selected)
Reverse charging (not selected)
Fast select (not selected)
Closed user group (not selected)
Other facilities (not selected)
One byte of call user data, X'BB', which is the protocol identifier
X.25 reset not supported by the user-defined communications application program
16KB is the maximum amount of contiguous data to be received
Automatic flow control value of 32

Figure 1-2. User Space to Send an SVC Call

5738SS1 V2R1M0  910524     i5/OS DUMP     006625/QSECOFR/QPADEV0001    12/21/90 12:47:42      PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- OUTPUTBUF                       CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        OUTPUTBUF                       TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:36:28              SIZE-          00001200
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       00A00100   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934D6E4 E3D7E4E3   C2E4C640 40404040 40404040 40404040  *  -  OUTPUTBUF   *
  000020   40404040 40404040 E0000000 00000000   00001000 00800000 00000000 00000000  *     \           *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *        (a       *
SPACE-
  000000   02000000 FFFFFFFF FFFFFFFF 00000000   00000008 40100001 00000000 00000000  *                 *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000040    TO    0000BF  SAME AS ABOVE
  0000C0   00000000 00000000 00000000 00000000   00000000 00000001 BB000000 00000000  *            Y    *
  0000E0   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000100    TO    0001BF  SAME AS ABOVE
  0001C0   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00004000  *                 *
  0001E0   00200000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
  000200   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000220    TO    000FFF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F2D8E2 C5C3D6C6   D9404040 F0F0F6F6 F2F7   *QPADEV0002QSECOFR   006627   *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *         1       *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F3F6 F2F84040  *V2R1M00901221123628 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                 *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                 *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                 *
  0000A0   00000000 00000000                                                          *                 *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

User Space Containing an Incoming X.25 Call, Operation X'B201'

This user space shows the following:

The call is using SVC 005
Both transmit and receive packet sizes are 128
Both transmit and receive window sizes are 7
The calling DTE address is 40100000
The called DTE address is 40200000
No other facilities are requested
One byte of call user data, X'BB', which is the protocol identifier

The application received this call because it had set a filter to indicate to the system that it should route incoming X.25 calls that have the first byte of call user data (the protocol identifier) equal to X'BB' to the application.

Figure 1-3. User Space Containing an Incoming X.25 Call

5763SS1 V3R1M0  940909   i5/OS DUMP      023099/QSYSOPR/QPADEV0014   03/07/94 11:57:24     PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- INBUFFER                        CONTEXT- USRDFNCMN
TYPE- *ALL SUBTYPE-*ALL
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        INBUFFER                        TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    03/07/94  11:53:15              SIZE-          0000002200
OWNER-       QSYSOPR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       000001DE7A00   0000
SPACE ATTRIBUTES-
  000000   00FFFF00 00000060 1934C9D5 C2E4C6C6   C5D94040 40404040 40404040 40404040  * -  INBUFFER       *
  000020   40404040 40404040 E0000000 00000000   00002000 00810000 00000000 00000000  *     \       a     *
  000040   00000000 00000000 00D601DE 73000400   00000000 00000000 00000000 00000000  *   O £   *
SPACE-
  000000   00000005 00800007 00800007 00000000   00000008 40100000 00000000 00000000  *                   *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                   *
        LINES  000040    TO    0000BF  SAME AS ABOVE
  0000C0   00000000 00000000 00000000 00000000   00000000 00000001 BB000000 00000000  *                   *
  0000E0   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                   *
        LINES  000100    TO    00013F  SAME AS ABOVE
  000140   00000000 00000000 00000000 00000000   00000000 00000000 08402000 00000000  *                   *
  000160   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                   *
        LINES  000180    TO    001FFF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F1F4D8E2 E8E2D6D7   D9404040 F0F2F3F0 F9F9   *QPADEV0014QSYSOPR   023099     *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *          1        *
  000020   40404040 40404040 404040E5 F3D9F1D4   F0F0F9F4 F0F3F0F7 F1F1F5F3 F1F54040  *V3R1M00940307115315 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                   *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                   *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                   *
  0000A0   00000000 00000000                                                          *                   *
USAGE-
  000000   D8E2E8E2 D6D7D940 4040D9C3 C8C1E2F3   F2F0                          *QSYSOPR   RCHAS320        *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

User Space to Accept an Incoming X.25 Call, Operation X'B400'

This user space was filled in to accept the incoming call, request default packet and window sizes, and no other additional facilities. The a maximum amount of contiguous data is set at 16KB and the automatic flow control is set at 32.

Figure 1-4. User Space to Accept an Incoming X.25 Call

5738SS1 V2R1M0  910524   i5/OS DUMP     006625/QSECOFR/QPADEV0001     12/21/90 12:48:06      PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- OUTBUFFER                       CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        OUTBUFFER                       TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:40:03              SIZE-          00002200
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       00A00A00   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934D6E4 E3C2E4C6   C6C5D940 40404040 40404040 40404040  * -  OUTBUFFER    *
  000020   40404040 40404040 E0000000 00000000   00002000 00800000 00000000 00000000  *        \        *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *           (a    *
SPACE-
  000000   00000000 FFFFFFFF FFFFFFFF 00000000   00000000 00000000 00000000 00000000  *                 *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000040    TO    0001BF  SAME AS ABOVE
  0001C0   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00004000  *                 *
  0001E0   00200000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
  000200   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000220    TO    001FFF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F1D8E2 C5C3D6C6   D9404040 F0F0F6F6 F2F   *QPADEV0001QSECOFR   006625     *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *          1       *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F4F0 F0F44040  *V2R1M00901221124004 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                  *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                  *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                  *
  0000A0   00000000 00000000                                                          *                  *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

User Spaces for Sending Data, Operation X'0000'

Two user spaces are shown below. The first is the output buffer and the second is the output buffer descriptor.

The user spaces below are filled in to send three data units of 512 bytes each. The first two data units have the more data indicator turned on, indicating that all the data units are contiguous.

Note: This link was enabled, specifying a data unit size of 512 bytes.

Figure 1-5. User Space (Buffer) to Send Three Data Units

5738SS1 V2R1M0  910524   i5/OS DUMP      006625/QSECOFR/QPADEV0001    12/21/90 12:55:19     PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- OUTPUTBUF                       CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        OUTPUTBUF                       TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:36:28              SIZE-          00001200
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       00A00100   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934D6E4 E3D7E4E3   C2E4C640 40404040 40404040 40404040  * -  OUTPUTBUF    *
  000020   40404040 40404040 E0000000 00000000   00001000 00800000 00000000 00000000  *        \        *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *           (a    *
SPACE-
  000000   F0F10000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *01               *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000040    TO    0001FF  SAME AS ABOVE
  000200   F0F20000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *02               *
  000220   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000240    TO    0003FF  SAME AS ABOVE
  000400   F0F30000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *03               *
  000420   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000440    TO    000FFF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F2D8E2 C5C3D6C6   D9404040 F0F0F6F6 F2F7   *QPADEV0002QSECOFR   006627    *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *           1      *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F3F6 F2F84040  *V2R1M00901221123628 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                  *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                  *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                  *
  0000A0   00000000 00000000                                                          *                  *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

Figure 1-6. User Space (Descriptor Element) to Describe the Three Data Units

5738SS1 V2R1M0  910524    i5/OS DUMP     006625/QSECOFR/QPADEV0001     12/21/90 12:55:58     PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- OUTPUTBUFD                      CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        OUTPUTBUFD                      TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:36:27              SIZE-          00000400
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       009FFE00   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934D6E4 E3D7E4E3   C2E4C6C4 40404040 40404040 40404040  *-  OUTPUTBUFD    *
  000020   40404040 40404040 E0000000 00000000   00000200 00800000 00000000 00000000  *        \        *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *           (a    *
SPACE-
  000000   02000100 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
  000020   02000100 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
  000040   02000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
  000060   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                 *
        LINES  000080    TO    0001FF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F2D8E2 C5C3D6C6   D9404040 F0F0F6F6 F2F7   *QPADEV0002QSECOFR   006627   *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *         1       *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F3F6 F2F74040  * V2R1M00901221123627 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                 *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                 *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                 *
  0000A0   00000000 00000000                                                          *                 *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

User Spaces for Receiving Data, Operation X'0001'

Two user spaces are shown below. The first is the input buffer and the second is the input buffer descriptor.

The user spaces below are filled in showing that 2 data units were received. The first data unit has the more data indicator turned on in the buffer descriptor for the data unit. This means that the X.25 more indicator was turned on in all the X.25 packets that this data unit contains. The second data unit does not have the more data indicator turned on, indicating that the last X.25 packet in the data unit had the X.25 more indicator turned off. The first and second data unit are considered to be logically contiguous to the application program.

Note: This link was enabled specifying a data unit size of 1024 bytes. The sending system sent the data in data unit sizes of 512 bytes and they were combined into the 1024 byte data unit size by the local system. The data unit size is not negotiated end-to-end, neither is the maximum amount of contiguous data or the automatic flow control. Because the values are important, each application should be aware of what the other application has specified for each value. Refer to Sending and Receiving Data Packets for more information.

Figure 1-7. User Space (Buffer) Containing the Three Data Units

5738SS1 V2R1M0  910524    i5/OS DUMP     006625/QSECOFR/QPADEV0001   12/21/90 12:59:33    PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- INBUFFER                        CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        INBUFFER                        TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:40:03              SIZE-          00002200
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       00A00400   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934C9D5 C2E4C6C6   C5D94040 40404040 40404040 40404040  * -  INBUFFER       *
  000020   40404040 40404040 E0000000 00000000   00002000 00800000 00000000 00000000  *     \             *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *           (a      *
SPACE-
  000000   F0F10000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *01                 *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                   *
        LINES  000040    TO    0001FF  SAME AS ABOVE
  000200   F0F20000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *02                 *
  000220   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                   *
        LINES  000240    TO    0003FF  SAME AS ABOVE
  000400   F0F30000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *03                 *
  000420   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                   *
        LINES  000440    TO    001FFF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F1D8E2 C5C3D6C6   D9404040 F0F0F6F6 F2F5   *QPADEV0001QSECOFR   006625     *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *           1       *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F4F0 F0F34040  * V2R1M00901221124003 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                   *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                   *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                   *
  0000A0   00000000 00000000                                                          *                   *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

Figure 1-8. User Space (Descriptor Element) Describing the Three Data Units

5738SS1 V2R1M0  910524    i5/OS DUMP    006625/QSECOFR/QPADEV0001   12/21/90 12:59:41     PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- INBUFFERD                       CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        INBUFFERD                       TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:40:03              SIZE-          00000400
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       00A00200   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934C9D5 C2E4C6C6   C5D9C440 40404040 40404040 40404040  *  -  INBUFFERD    *
  000020   40404040 40404040 E0000000 00000000   00000200 00800000 00000000 00000000  *        \         *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *           (a     *
SPACE-
  000000   04000100 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                  *
  000020   02000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                  *
  000040   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                  *
        LINES  000060    TO    0001FF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F1D8E2 C5C3D6C6   D9404040 F0F0F6F6 F2F5   *QPADEV0001QSECOFR   006625    *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *            1     *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F4F0 F0F34040  * V2R1M00901221124003 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                  *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                  *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                  *
  0000A0   00000000 00000000                                                          *                  *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

User Space to Clear a Connection or Call, Operation X'B100'

This user space was filled in to end an SVC connection or clear an incoming call. No facilities or clear user data are requested with this, but cause and diagnostic codes are specified (these are not ISO or SNA codes).

Figure 1-9. User Space to Send an SVC Clear

5738SS1 V2R1M0  910524      i5/OS DUMP    006625/QSECOFR/QPADEV0001    12/21/90 13:14:48     PAGE   1
DMPSYSOBJ PARAMETERS
OBJ- OUTBUFFER                       CONTEXT-USRDFNCMN
OBJTYPE- *USRSPC
OBJECT TYPE-           SPACE                                           *USRSPC
NAME-        OUTBUFFER                       TYPE-          19   SUBTYPE-          34
LIBRARY-     USRDFNCMN                       TYPE-          04   SUBTYPE-          01
CREATION-    12/21/90  12:40:03              SIZE-          00002200
OWNER-       QSECOFR                         TYPE-          08   SUBTYPE-          01
ATTRIBUTES-          0800                    ADDRESS-       00A00A00   0000
SPACE ATTRIBUTES-
  000000   00000080 00000060 1934D6E4 E3C2E4C6   C6C5D940 40404040 40404040 40404040  *  -  OUTBUFFER  *
  000020   40404040 40404040 E0000000 00000000   00002000 00800000 00000000 00000000  *        \       *
  000040   00000000 00000000 0005004D 42000400   00000000 00000000 00000000 00000000  *           (a   *
SPACE-
  000000   0000BEBE 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *  XX            *
  000020   00000000 00000000 00000000 00000000   00000000 00000000 00000000 00000000  *                *
        LINES  000040    TO    001FFF  SAME AS ABOVE
POINTERS-
  NONE
OIR DATA-
TEXT-
  000000   D8D7C1C4 C5E5F0F0 F0F1D8E2 C5C3D6C6  D9404040 F0F0F6F6 F2F5   *QPADEV0001QSECOFR   006625  *
SERVICE-
  000000   40404040 40404040 40404040 40404040   40404040 40F14040 40404040 40404040  *        1       *
  000020   40404040 40404040 404040E5 F2D9F1D4   F0F0F9F0 F1F2F2F1 F1F2F4F0 F0F44040  * V2R1M00901221124004 *
  000040   40404040 40404040 40404040 40404040   40404040 40404040 40404040 40404040  *                *
  000060   40404040 40404040 40404040 40404040   40404040 40404040 00000000 00000000  *                *
  000080   00000000 00000000 00000000 00000000   00000000 00000000 40400000 00000000  *                *
  0000A0   00000000 00000000                                                          *                *
END OF DUMP
                                          * * * * *  E N D  O F  L I S T I N G  * * * * *

Error Codes

The system and user-defined communications support reports important information that is useful for determining recovery actions when an error occurs. This information is referred to as error codes that are reported either to the job log or to the QSYSOPR message queue. For a complete list of the messages that are signaled by the user-defined communications APIs, see Messages.

In some cases error codes are reported to your application in the error specific parameter. The following sections list the valid error codes. Some of the error codes represent actual coding errors, others only report additional information. For information about the error codes for the individual user-defined communications APIs, see User-Defined Communications Support APIs.

Local Area Network (LAN) Error Codes

Figure 1-10 shows the valid hexadecimal codes your application can receive as a result of a call to the QOLSEND API using operation code X'0000'. The codes indicate that the data was never sent on the line. Associated with these error codes is a message in QSYSOPR, indicating the device description that caused the error, and the error code. After receiving the error code, the link will still be enabled and usable.

These error codes indicate to your application that a coding error was made and should be corrected.

Figure 1-10. Error Codes Received While Sending Data over LAN

Error Code	Description	Cause
3300 2A55	Routing length not valid	Routing length is not valid, or length does not equal length in routing field.
3300 2A5D	Maximum frame size limit exceeded	Length of data is greater than maximum frame size supported by the source SAP
5300 2A7B	Access Control not valid	Access Control specified is not supported
3300 2AA9	SAP address not valid	SAP address is not configured in the line description
3300 2AA9	SAP address not valid	SAP address is not configured in the line description
3300 2AD4	Data length too small (Ethernet Version 2 only)	Data must be at least 48 bytes long (46 bytes of data, plus 2 bytes for the Ethernet type field)
3300 2AD5	Ethernet type field is not valid (Ethernet Version 2 only)	Ethernet type field (first two bytes of data)

X.25 Error Codes

Figure 1-11 shows the valid error codes your application can receive as a result of

A call to the QOLSEND API with operation X'B400' to accept an SVC call
A call to the Receive Data (QOLRECV) API which returns the results of the open connection request operation, X'B101'
The connection failure indication, reported by operation X'B301'

These error codes indicate to your application that a coding error was made, or a failure condition occurred.

Figure 1-11. Error Codes Reported on X'B001', X'B301', and X'B400' Operations

Error Code	Description	Cause
1200 3122	Outgoing channel not available	The logical channel is still active and in the process of being deactivated
3200 3050	Restart in progress	Temporary condition; retry operation
3200 3172	Outgoing channel not available	Temporary condition; retry operation
3200 3368	Remote address length not valid	Remote address length not supported by the network
3200 3384	Facility field error	A facility was encoded incorrectly or a duplicate facility was encoded
3200 3388	Facility field too long	The total length of the facilities, which includes user-specified facilities, the NUI facility from the line description, and system generated facilities, exceeded X.25 limits (109 bytes)
3200 338C	Response restricted by fast select	User data is not allowed with restriction
3200 3394	User data not allowed	User data is not allowed on the call accept if fast select was not requested.
3200 33CC	Call user data length not valid	The length of call user data is greater than 16 and fast select is not selected.
4200 3210	Reset request transmitted	The virtual circuit was reset by the local system. Refer to cause and diagnostic codes to determine recovery.
4200 3220	Clear request transmitted	The virtual circuit was cleared by the local system. Refer to cause and diagnostic codes to determine recovery.
4200 3222	Clear request transmitted	The virtual circuit was cleared by the local system because there was a problem with the packet size in the call accept. This is either a configuration problem or a network problem. Verify that the default packet size in the line description is correct.
4200 3224	Clear request transmitted	The virtual circuit was cleared by the local system because there was a problem with the window size in the call accept. This is either a configuration problem or a network problem. Verify that the default window size in the line description is correct.
4200 3230	Restart request transmitted	The virtual circuit was cleared by the local system. Refer to cause and diagnostic codes for more information.
4200 3280	Time-out on call	Call timed out
4600 3134	Clear indication was received	The virtual circuit was cleared by either the remote system or the network. Refer to cause and diagnostic codes for more information.
4600 3138	Restart indication received	Temporary condition; refer to the cause and diagnostic codes reported to correct the problem, then retry the operation

Figure 1-12 shows the valid error codes your application can receive as a result of a call to the QOLRECV API with an operation code returned as X'B101'.

These error codes indicate to your application that the connection was cleared or reset for the following reasons.

Figure 1-12. Error Codes Reported on the X'B101' Operation

Error Code	Description	Cause
3200 3388	Facility field too long	The total length of the facilities, which includes user-specified facilities, the NUI facility from the line description, and system generated facilities, exceeded X.25 limits (109 bytes)
3200 3394	User data not allowed	User data is not allowed when fast select is not selected.
3200 33CC	Call user data length not valid	The length of call user data is greater than 16 and fast select is not selected.
4200 3240	Time-out on reset	The clear request resulted in an X.25 reset, which timed out
4200 3284	Time-out on clear	The remote system did not respond to the CLEAR within the time-out value
4600 3134	Clear indication was received	The virtual circuit was cleared by either the remote system or the network. Refer to cause and diagnostic codes for more information.

Figure 1-13 shows the valid error codes your application can receive as a result of a call to the QOLRECV API, returning the operation code, X'BF01'.

These error codes indicate to your application that the connection was cleared or reset for the following reasons.

Figure 1-13. Error Codes Reported on the X'BF01' Operation

Error Code	Description	Cause
3200 3050	Network Restart in progress	Temporary condition; connection is no longer active.
3200 3A0C	Close pending	The virtual circuit is being closed.
3200 3A0D	Reset pending	The virtual circuit is in the process of being reset by either the remote system or the network.
4200 3210	Reset packet transmitted	A Reset packet was transmitted from the local system.
4200 3240	Time-out on reset	The clear request resulted in an X.25 reset, which timed out
4600 3130	Reset indication was received	The virtual circuit received a reset by either the remote system or the network. Refer to cause and diagnostic codes for more information.
4600 3134	Clear indication was received	The virtual circuit was cleared by either the remote system or the network. Refer to cause and diagnostic codes for more information.

Figure 1-14 shows the valid error codes your application can receive as a result of a call to the QOLSEND API with an operation code returned as X'0000'.

These error codes indicate to your application that the connection was cleared or reset for the following reasons.

Figure 1-14. Error Codes Resulting from a X'0000' Operation

Error Code	Description	Cause
3200 3050	Network restart in progress	Temporary condition; connection is no longer active.
3200 336A	Q/M bit sequence not valid	If the data is qualified, the Q bit must be set for all data units.
3200 33C8	Data length not valid	The length of the packet is not supported for this virtual circuit.
3200 3A0C	Close pending	The virtual circuit is being closed.
3200 3A0D	Reset pending	The virtual circuit is in the process of being reset by either the remote system or the network.
4200 3284	Interrupt timed out	The local DTE sent an interrupt packet. The response to this packet was not received within the time-out period, and the connection has been reset by the iSeries server.
4600 3130	Reset indication was received	The virtual circuit received a reset by either the remote system or the network. Refer to cause and diagnostic codes for more information.
4600 3134	Clear indication was received	The virtual circuit was cleared by either the remote system or the network. Refer to cause and diagnostic codes for more information.

Common Errors and Messages

This section shows some of the common errors that you or your application programmer may encounter. Some of these errors are detected by the APIs and reported to the application by the unsuccessful return and reason codes returned on each API. Other errors are program design errors, that your application programmer must detect and correct. The errors are listed by category:

Parameter Errors

Switching use of connection identifiers (PCEP and UCEP)
Switching use of timer handles
Not encoding parameters if not used
Operation code not in hexadecimal format
Parameter not declared with proper length

User Space Errors

Not encoding reserved space for fields not used
Not initializing user space fields as necessary.
The output user spaces can only be changed by the user-defined communications application. Operations are validated on each request. If there are fields that the current operation does not use, they should be set to contain zeros with X'00', to prevent a template error resulting from information on the previous operation still being in the user space. Not resetting the indicators in the output buffer descriptors on each operation and not zeroing out fields before making a call request may result in template errors.

Queue Errors

Queue not created
Queue created with different key length than specified in the parameter list of the Enable Link (QOLELINK) API

Receive Data (QOLRECV) API Errors

Not checking the more data output parameter and issuing another call to the QOLRECV API
Not calling the QOLSETF API to set the filter to route inbound data to the application
Using the wrong data unit descriptor for the data unit (each data unit has its own descriptor)

Send Data (QOLSEND) API Errors

After a call to the QOLSEND API with an operation code of X'B000', X'B100', or X'BF00', the application should then call the QRCVDTAQ API and wait for incoming data to be placed on the queues. The success or failure of these operations is reported through the QOLRECV API with operation codes of X'B001', X'B101' and X'BF01', respectively.
Using the wrong data unit descriptor for the data unit (each data unit has its own descriptor)

Enable Link (QOLELINK) API Errors

User space names not unique
Queue not created before program call
Line description not created or incorrect prior to program call

Query Line Description (QOLQLIND) API Errors

Parameter buffer not large enough

Top | Communications APIs | APIs by category