Method 3: UA for service location and CM_CSLIST_GETII for load-balancing

The CM_CSLIST_GETII primitive is provided for QEL/MU emulators. The primitive is extended to allow multiple filters to be supplied by the application. The header file cmi.h contains structures and definitions for this method and is included in this SDK. To use this method, the following procedure applies:

  1. The application issues SL_Open to open a session with SLP.
  2. If a scope is not configured or is not otherwise made available to the app, the application issues an SL_GetAttrs API call for the 'cs3270' service type with an attribute tag filter of 'SCOPE' to obtain valid, reachable scopes. This API returns a list of scopes that correspond to service URLs of Communications Server that can respond to the IP-version CM_CSLIST_GETII primitive.
  3. The application issues SL_GetService specifying the 'cs3270' service only, and a valid scope. The Service reply contains a list of URLs of servers to which the application can connect that can handle the CM_CSLIST_GETII primitive.
  4. The application connects to the server represented by any selected URL in the list.
  5. The application issues SL_Close to close the SLP session.
  6. The application builds a CM_CSLIST_GETII primitive to retrieve a load-balanced list of servers. In it, the AgentType field is set to the desired service, and the filter specification contains the scope and the LU Pool name (if applicable).
  7. A CM_CSLIST_GETII_ACK is returned containing a list of server TCP/IP addresses in load-balanced order (least-loaded to highest).
  8. The application selects the first server in the list and connects to it.
  9. The application tries to establish an SNA session with the server. If unsuccessful, it repeats the previous step with the next server in the returned list (and so on) until it succeeds or the list is exhausted.
Table 1. CM_CSLIST_GETII Primitive
Field name Field offset (hex) Field length (dec) Type Content and Use
PrimType x00 4 long int CM_CSLIST_GETII as in cmi.h.
UserParm x04 4 long int Any value you want returned in the reply.
Reserved x08 4 long int zero
ServiceType x0c 4 long int 0x12B (for load balancing support)
ProdVersion x10 4 long int -1 (indicates "don't care")
NWVersion x14 4 long int -1 (indicates "don't care")
Flags x18 4 long int See Flags values (from cmi.h).
AgentType x0c 4 long int See AgentType values (from csobjtyp.h).
FilterList x1c * FilterList_t See FilterList_t (if Flags = CMCsListFlag_LBPool) or FilterList_t (if Flags = zero | Flags = CMCsListFlag_LBFilters) (value depends on setting of flags).
Table 2. CM_CSLIST_GETII Primitive
Constant Value Meaning
zero 0 Need an unordered list. No filters are specified. (Provided for backwards compatibility.)
CMCsListFlags_LBPool 1 Need load-balanced list specifying a load-balanced pool name. (Value provided for backwards compatibility.)
CMCsListFlags_LBAgent 2 Need load-balanced list. AgentType is used for load-balancing.
CMCsListFlags_LBFilter 3 Need load-balanced list. A variable-length list of filters follows.
Table 3. Flags values (from cmi.h)
Constant Value Meaning
CSA_3270 0x126 Need an SNA Gateway agent for LU Types 1/2/3
CSA_SAA 0x12B Need an SNA Gateway agent for LU Type 6.2
Table 4. AgentType values (from csobjtyp.h)
Field name Field offset (hex) Field length (dec) Type Content and Use
FilterNameLen x00 4 long int Length of following load-balancing group (Pool) name.
FilterName x04 * ASCII Load-balancing group (Pool) name.
Table 5. FilterList_t (if Flags = CMCsListFlag_LBPool)
Field name Field offset (hex) Field length (dec) Type Content and Use
FilterCount x00 4 long int Number of filter list name structures that follow (0, if Flags = zero).
FilterList x04 * Filter_t A list of filter list name structures. Each structure has variable length.
Table 6. FilterList_t (if Flags = zero | Flags = CMCsListFlag_LBFilters)
Field name Field offset (hex) Field length (dec) Type Content and Use
FilterLength x00 4 long int Length of structure (plus this length field).
FilterType x04 4 long int See FilterType values (from cmi.h).
FilterName x08 * ASCII The filter name value.
Table 7. Filter_t
Constant Meaning
CMCsListFilter_LBPool A Load-balancing Pool name. Only one pool may be specified per list. This filter is valid only for AgentType CSA_3270.
CMCsListFilter_Scope An SLP Scope name. Only one scope may be specified. If no scope is specified, then all unscoped services are assumed.
Table 8. FilterType values (from cmi.h)
Field name Field offset (hex) Field length (dec) Type Content and Use
PrimType x00 4 long int CM_CSLIST_GETII_ACK as in cmi.h.
UserParm x04 4 long int As passed in on CM_CSLIST_GETII.
Reserved x08 4 long int zero
ServiceType x0c 4 long int As passed in on CM_CSLIST_GETII.
Flags x10 4 long int As passed in on CM_CSLIST_GETII.
ServiceCount x14 4 long int Number of following server entries.
Table 9. CM_CSLIST_GETII_ACK Primitive
Field name Field offset (hex) Field length (dec) Type Content and Use
ProdVersion x00 4 long int Version of product.
Platform x04 4 long int CMCsListPlatform_IWSAA
CSNameLen x08 4 long int Length of following server name.
CSName * * long int Name of server (null-terminated).
CSAddrLen * 4 long int Length of following IP address.
CSAddress * * ASCII The IP address of the server in the form: dotted-decimal-IP-address:port.
NameLen * 4 long int Length of following agent name.
AgentName * * * Name of agent on server (null-terminated).
Table 10. Server Information structure in CM_CSLIST_GETII_ACK Primitive
Field name Field offset (hex) Field length (dec) Type Content and Use
PrimType x00 4 long int CM_CSLIST_GETII_ERR as in cmi.h.
UserParm x04 4 long int As passed in on CM_CSLIST_GETII.
Reserved x08 4 long int zero
Errno x0c 4 long int Error number