Configuration and Queue Entries

• Configure user-defined communications support
  
  
• Set up the entries that user-defined communications support can send to the queue

Configuring User-Defined Communications Support

This section describes what needs to be configured before your application program can use the user-defined communications APIs. You can either use the system-supplied menus or the Control Language (CL) commands to do this configuration. For more information about using queue APIs, see Object APIs.

Links

Links allow your application program to use a token-ring, Ethernet, FDDI, wireless, or X.25 communications line. A link is made up of the following communications objects:

• Token-ring, Ethernet, FDDI, wireless, or X.25 line description
  
  
• Network controller description
  
  
• Network device description of type *USRDFN
  
  
• Network interface description for ISDN (X.25 only)

You need to configure the line description; user-defined communications support automatically configures a network controller and a network device description of type *USRDFN when the link is enabled. If you are using X.25 over ISDN, the network interface description must also be configured. The network interface, line, controller, and device descriptions are automatically varied on, if necessary.

Use the following commands to create or change line descriptions:

• CRTLINDDI -- Create Line Description (DDI)
  
  
• CHGLINDDI -- Change Line Description (DDI)
  
  
• CRTLINETH -- Create Line Description (Ethernet)
  
  
• CHGLINETH -- Change Line Description (Ethernet)
  
  
• CRTLINTRN -- Create Line Description (Token-Ring)
  
  
• CHGLINTRN -- Change Line Description (Token-Ring)
  
  
• CRTLINWLS -- Create Line Description (Wireless)
  
  
• CHGLINWLS -- Change Line Description (Wireless)
  
  
• CRTLINX25 -- Create Line Description (X.25)
  
  
• CHGLINX25 -- Change Line Description (X.25)

Use the following commands to create or change controller descriptions:

• CRTCTLNET -- Create Controller Description (Network)
  
  
• CHGCTLNET -- Change Controller Description (Network)

Use the following commands to create or change device descriptions:

• CRTDEVNET -- Create Device Description (Network)
  
  
• CHGDEVNET -- Change Device Description (Network)

Use the following commands to create or change network interface descriptions:

• CRTNWIISDN -- Create Network Interface Description (ISDN)
  
  
• CHGNWIISDN -- Change Network Interface Description (ISDN)

See the Communications Configuration manual, SC41-5401, for more information about configuring communications. This manual is not included in this release of the IBM^® i Information Center; however, it is available from the IBM Publications Center as a printed hardcopy that you can order or in an online format that you can download at no charge.

Queue

User-defined communications support uses a queue to inform your application program of some action to take or of an activity that is complete. You must create the queue before the link is enabled.

The size of each queue entry must be large enough to accommodate the user-defined communications support entries. See the following Queue Entries for more information about the entries that user-defined communications support can send to the queue.

Use the Create Data Queue (CRTDTAQ) command to create your data queues. Use the QUSCRTUQ and QUSDLTUQ APIs to create and delete your user queues.

Queue Entries

This section describes the entries user-defined communications support can send to the queue.

General format

The length of each entry is always at least 80 bytes. When using a keyed queue, however, each entry can be as large as 336 bytes, depending on the size of the key value supplied to the user-defined communications support.

Table 1 shows the general format of each user-defined communications support entry.

Table 1. Queue Entry General Format

Entry type

This indicates the type of entry on the queue and will be *USRDFN for all user-defined communications support entries.

Entry ID

This uniquely identifies each entry within an entry type. User-defined communications support has five entries defined:

• Enable-complete entry (entry ID = '00')
• Disable-complete entry (entry ID = '01')
• Permanent-link-failure entry (entry ID = '02')
• Incoming-data entry (entry ID = '03')
• Timer-expired entry (entry ID = '04')

Note: The entry type of *USRDFN and all associated entry IDs, either defined or undefined, are reserved for user-defined communications support. Therefore, your application program should not define entries using this entry type.

Entry data

This data is useful to your application program and varies according to the entry ID.

Key

When using a keyed queue, this is the key value supplied to the user-defined communications support.

Enable-complete entry

The enable-complete entry is sent to the queue when the enable link operation is complete. This entry is only sent after the Enable Link (QOLELINK) API returns to your application program with a successful return and reason code.

Note: The QOLELINK API only initiates the enabling of the link. Your application program must wait for the enable-complete entry before attempting to perform input or output on the link.

Table 2 shows the format of the enable-complete entry.

Table 2. Enable-Complete Entry

Communications handle

The name of the link that is being enabled. Your application program supplies this name when the QOLELINK API is called.

Status

This indicates the outcome of the enable link operation. A character value of zero indicates the enable link operation was successful and I/O is now possible on this link. A character value of one indicates the enable link operation was not successful (the job log contains messages indicating the reason). The user-defined communications support disables the link when the enable link operation does not complete successfully and the disable-complete entry is not sent to the queue.

Key

The key value associated with the enable-complete entry when using a keyed queue. Your application program supplies this key value when the QOLELINK API is called. When using a non-keyed queue (indicated by supplying a key length of zero to the QOLELINK API) this field is not present.

Disable-complete entry

The disable-complete entry is sent to the queue when a link is successfully disabled. This entry is always the last entry sent by the user-defined communications support on this link and, therefore, provides a way for your application program to remove any enable-complete, incoming-data, or permanent-link-failure entries previously sent to the queue.

Note: User-defined communications support does not associate timers with links. Therefore, it is possible for a timer-expired entry to be sent to the queue after the link is disabled. Your user-defined communications application program is responsible for handling this.

Table 3 shows the format of the disable-complete entry.

Table 3. Disable-Complete Entry

Communications handle

The name of the link that has been disabled. Your application program supplies this name when the QOLELINK API is called to enable the link.

Key

The key value associated with the disable-complete entry, when using a keyed queue. Your application program supplies this key value when the QOLELINK API is called to enable the link. When using a non-keyed queue (indicated by supplying a key length of zero to the QOLELINK API) this field is not present.

Permanent-link-failure entry

The permanent-link-failure entry is sent to the queue when error recovery is canceled on a link. You must disable and then enable the link to recover.

Table 4 shows the format of the permanent-link-failure entry.

Table 4. Permanent-Link-Failure Entry

Communications handle

The name of the link on which the failure has occurred. Your application program supplies this name when the QOLELINK API is called to enable the link.

Key

The key value associated with the permanent-link-failure entry, when using a keyed queue. Your application program supplies this key value when the QOLELINK API is called to enable the link. When using a non-keyed queue (indicated by supplying a key length of zero to the QOLELINK API) this field is not present.

Incoming-data entry

The incoming-data entry is sent to the queue when the user-defined communications support has data for your application program to receive. Your application program should call the Receive Data (QOLRECV) API to pick up the data when this entry is received.

Note: Another incoming-data entry is not sent to the queue until your application program picks up all the data from the user-defined communications support. The data available parameter on the call to the QOLRECV API indicates that the receipt of data is not complete.

Table 5 shows the format of the incoming-data entry.

Table 5. Incoming-Data Entry

Communications handle

The name of the link on which the data has come in. Your application program supplies this name when the QOLELINK API is called to enable the link.

Key

The key value associated with the incoming-data entry, when using a keyed queue. Your application program supplies this key value when the QOLELINK API is called to enable the link. When using a non-keyed queue (indicated by supplying a key length of zero to the QOLELINK API) this field is not present.

Timer-expired entry

The timer-expired entry is sent to the queue when a timer, previously set by your application program, ends.

Table 6 shows the format of the timer-expired entry.

Table 6. Timer-Expired Entry

Timer handle

The name of the expired (ended) timer. Your application program returns this name when the Set or Cancel Timer (QOLTIMER) API is called to set the timer.

User data

The data associated with the expired timer. Your application program supplies this data when the QOLTIMER API is called to set the timer.

Key

The key value associated with the timer-expired entry, when using a keyed queue. Your application program supplies this key value when the QOLTIMER API is called to set the timer. When using a non-keyed queue (indicated by supplying a key length of zero to the QOLTIMER API) this field is not present.

[ Back to top | Communications APIs | APIs by category ]