EZACIC08

The GETHOSTBYNAME and GETHOSTBYADDR calls were derived from C socket calls that return a structure known as HOSTENT. A given TCP/IP host can have multiple alias names and host IP addresses.

TCP/IP uses indirect addressing to connect the variable number of alias names and IP addresses in the HOSTENT structure that are returned by the GETHOSTBYADDR and GETHOSTBYNAME calls.

If you are coding in PL/I or assembly language, the HOSTENT structure can be processed in a relatively straight-forward manner. However, if you are coding in COBOL, HOSTENT can be more difficult to process and you should use the EZACIC08 subroutine to process it for you.

It works as follows:

GETHOSTBYADDR or GETHOSTBYNAME returns a HOSTENT structure that indirectly addresses the lists of alias names and IP addresses.
Upon return from GETHOSTBYADDR or GETHOSTBYNAME, your program calls EZACIC08 and passes it the address of the HOSTENT structure. EZACIC08 processes the structure and returns the following information:
- The length of host name, if present
- The host name
- The number of alias names for the host
- The alias name sequence number
- The length of the alias name
- The alias name
- The host IP address type, always 2 for AF_INET
- The host IP address length, always 4 for AF_INET
- The number of host IP addresses for this host
- The host IP address sequence number
- The host IP address
If the GETHOSTBYADDR or GETHOSTBYNAME call returns more than one alias name or host IP address, the application program should repeat the call to EZACIC08 until all alias names and host IP addresses have been retrieved.

Figure 1 shows an example of EZACIC08 call instructions.

Figure 1. EZAZIC08 call instruction example

     WORKING-STORAGE SECTION.
 
         01  HOSTENT-ADDR       PIC 9(8) BINARY.
         01  HOSTNAME-LENGTH    PIC 9(4) BINARY.
         01  HOSTNAME-VALUE     PIC X(255).
         01  HOSTALIAS-COUNT    PIC 9(4) BINARY.
         01  HOSTALIAS-SEQ      PIC 9(4) BINARY.
         01  HOSTALIAS-LENGTH   PIC 9(4) BINARY.
         01  HOSTALIAS-VALUE    PIC X(255).
         01  HOSTADDR-TYPE      PIC 9(4) BINARY.
         01  HOSTADDR-LENGTH    PIC 9(4) BINARY.
         01  HOSTADDR-COUNT     PIC 9(4) BINARY.
         01  HOSTADDR-SEQ       PIC 9(4) BINARY.
         01  HOSTADDR-VALUE     PIC 9(8) BINARY.
         01  RETURN-CODE        PIC 9(8) BINARY.
 
     PROCEDURE DIVISION.
 
        CALL 'EZASOKET' USING 'GETHOSTBYADDR'
                        HOSTADDR HOSTENT-ADDR
                        RETCODE.
 
        CALL 'EZASOKET' USING 'GETHOSTBYNAME'
                        NAMELEN NAME HOSTENT-ADDR
                        RETCODE.
 
        CALL 'EZACIC08' USING HOSTENT-ADDR HOSTNAME-LENGTH
                        HOSTNAME-VALUE HOSTALIAS-COUNT HOSTALIAS-SEQ
                        HOSTALIAS-LENGTH HOSTALIAS-VALUE
                        HOSTADDR-TYPE HOSTADDR-LENGTH HOSTADDR-COUNT
                        HOSTADDR-SEQ HOSTADDR-VALUE RETURN-CODE.

For equivalent PL/I and assembly language declarations, see Converting parameter descriptions.

Parameter values set by the application

HOSTENT-ADDR: This fullword binary field must contain the address of the HOSTENT structure (as returned by the GETHOSTBYxxxx call). This variable is the same as the variable HOSTENT in the GETHOSTBYADDR and GETHOSTBYNAME socket calls.
HOSTALIAS-SEQ: This halfword field is used by EZACIC08 to index the list of alias names. When EZACIC08 is called, it adds 1 to the current value of HOSTALIAS-SEQ and uses the resulting value to index into the table of alias names. Therefore, for a given instance of GETHOSTBYxxxx, this field should be set to 0 for the initial call to EZACIC08. For all subsequent calls to EZACIC08, this field should contain the HOSTALIAS-SEQ number returned by the previous invocation.
HOSTADDR-SEQ: This halfword field is used by EZACIC08 to index the list of IP addresses. When EZACIC08 is called, it adds 1 to the current value of HOSTADDR-SEQ and uses the resulting value to index into the table of IP addresses. Therefore, for a given instance of GETHOSTBYxxxx, this field should be set to 0 for the initial call to EZACIC08. For all subsequent calls to EZACIC08, this field should contain the HOSTADDR-SEQ number returned by the previous call.

Parameter values returned to the application

HOSTNAME-LENGTH

This halfword binary field contains the length of the host name (if host name was returned).

HOSTNAME-VALUE

This 255-byte character string contains the host name (if host name was returned).

HOSTALIAS-COUNT

This halfword binary field contains the number of alias names returned.

HOSTALIAS-SEQ

This halfword binary field is the sequence number of the alias name currently found in HOSTALIAS-VALUE.

HOSTALIAS-LENGTH

This halfword binary field contains the length of the alias name currently found in HOSTALIAS-VALUE.

HOSTALIAS-VALUE

This 255-byte character string contains the alias name returned by this instance of the call. The length of the alias name is contained in HOSTALIAS-LENGTH.

HOSTADDR-TYPE

This halfword binary field contains the type of host address. For FAMILY type AF_INET, HOSTADDR-TYPE is always 2.

HOSTADDR-LENGTH

This halfword binary field contains the length of the host IP address currently found in HOSTADDR-VALUE. For FAMILY type AF_INET, HOSTADDR-LENGTH is always set to 4.

HOSTADDR-COUNT

This halfword binary field contains the number of host IP addresses returned by this instance of the call.

HOSTADDR-SEQ

This halfword binary field contains the sequence number of the host IP address currently found in HOSTADDR-VALUE.

HOSTADDR-VALUE

This fullword binary field contains a host IP address.

RETURN-CODE

This fullword binary field contains the EZACIC08 return code:

Value: Description
0: Successful completion.
-1: HOSTENT address is not valid.
-2: A value of HOSTALIAS-SEQ is not valid.
-3: A value of HOSTADDR-SEQ is not valid.