QUERY_SNA

QUERY_SNA_NET returns information about servers that can act as backup master servers, as defined in the sna.net file. It can be used to obtain information about a specific server or about multiple servers, depending on the options used.

The ordering of server names in this file is significant; the first server listed in the file will always be the master if it is active, the second will be the master if the first is inactive, the third will be the master if the first and second are both inactive, and so on. Because of this, the list of server names returned on QUERY_SNA_NET is in the same order as it is in the file; the returned names are not ordered by name length and lexicographical ordering, as with other QUERY_* verbs.

This verb must be issued to the sna.net file.

VCB Structure

typedef struct query_sna_net
{
   AP_UINT16        opcode;                  /* Verb operation code          */
   unsigned char    reserv2;                 /* reserved                     */
   unsigned char    format;                  /* reserved                     */
   AP_UINT16        primary_rc;              /* Primary return code          */
   AP_UINT32        secondary_rc;            /* Secondary return code        */
   unsigned char    *buf_ptr;                /* pointer to buffer            */
   AP_UINT32        buf_size;                /* buffer size                  */
   AP_UINT32        total_buf_size;          /* total buffer size required   */
   AP_UINT16        num_entries;             /* number of entries            */
   AP_UINT16        total_num_entries;       /* total number of entries      */
   unsigned char    list_options;            /* listing options              */
   unsigned char    reserv3;                 /* reserved                     */
   unsigned char    security;                /* security for Windows clients */
   unsigned char    domain_name[64];         /* domain name                  */
   unsigned char    server_name[64];         /* master or backup server name */
   unsigned char    reserv4[4];              /* reserved                     */
} QUERY_SNA_NET;

typedef struct backup_summary
{
   AP_UINT16        overlay_size;            /* size of returned entry       */
   unsigned char    reserv1[2];              /* reserved                     */
   unsigned char    server_name[64];         /* master or backup server name */
   unsigned char    reserv2[4];              /* reserved                     */
} BACKUP_SUMMARY;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_SNA_NET

overlay_size

For compatability with future releases of SNAplus2, your application must use this field to determine the exact length of the overlay structure returned, and should not rely on the use of the sizeof() function.

buf_ptr

A pointer to a data buffer that SNAplus2 will use to return the requested information.

buf_size

Size of the supplied data buffer.

num_entries

Maximum number of server names for which data should be returned. To request a specific entry rather than a range, specify the value 1. To return as many entries as possible, specify zero; in this case, SNAplus2 will return the maximum number of entries that can be accommodated in the supplied data buffer.

list_options

The position in the list from which SNAplus2 should begin to return data.

Specify one of the following values:

AP_FIRST_IN_LIST: Start at the first entry in the list.
AP_LIST_INCLUSIVE: Start at the entry specified by the server_name parameter.
AP_LIST_FROM_NEXT: Start at the entry immediately following the entry specified by the server_name parameter.

For more information about how the application can obtain specific entries from the list, see “List Options For QUERY_* Verbs”. The server names are listed in the same order as in the file, not in order of name length and/or lexicographical order as for other QUERY_* verbs.

server_name

Name of the server for which information is required, or the name to be used as an index into the list of servers. The server name is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters: Successful Execution

If the verb executes successfully, SNAplus2 returns the following parameters:

primary_rc

AP_OK

buf_size

Length of the information returned in the supplied buffer.

total_buf_size

Returned value indicating the size of buffer that would have been required to return all the list information requested. A value greater than buf_size indicates that not all the available entries were returned.

num_entries

Number of entries returned in the data buffer.

total_num_entries

Total number of entries available. A value greater than num_entries indicates that not all the available entries were returned.

security

The level of security for Windows clients accessing SNAplus2 servers. This is specified during installation, or can be modified later using the snapwinsec program; for more information about security for Windows clients, refer to the HP-UX SNAplus2 Administration Guide. Possible values are:

AP_SECURITY_OFF: No security restrictions.
AP_SECURITY_DOMAIN: Login IDs and passwords used by Windows Client users must be defined on the HP-UX system.

domain_name

The name of the TCP/IP domain containing the SNAplus2 LAN. This name was specified during installation of the master server.

Each entry in the data buffer consists of the following parameters:

backup_summary.overlay_size

The size of the returned backup_summary structure, and therefore the offset to the start of the next entry in the data buffer.

backup_summary.server_name

Server name.

Returned Parameters: Parameter Check

If the verb does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

AP_PARAMETER_CHECK

secondary_rc

AP_INVALID_LIST_OPTION: The list_options parameter was not set to a valid value.

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

Returned Parameters: State Check

If the verb does not execute because of a state check, SNAplus2 returns the following parameters.

primary_rc

AP_STATE_CHECK

secondary_rc

Possible values are:

AP_RECORD_NOT_FOUND: The list_options parameter was set to AP_LIST_INCLUSIVE or AP_LIST_FROM_NEXT to list entries starting from the supplied server name, but the backup_name parameter did not match an entry in the file. If the supplied name was one returned on a previous QUERY_SNA_NET verb, this indicates that the list has been updated (by another administration program or NOF application) since the previous verb; the application should reissue QUERY_SNA_NET to obtain the complete list.
AP_INVALID_TARGET: The target handle on the NOF API call specified a configuration file or a node. This verb must be issued to the sna.net file.

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_STATE_CHECK, which are common to all NOF verbs.

Returned Parameters: Other Conditions

Appendix A “Common Return Codes” lists further combinations of primary and secondary return codes that are common to all NOF verbs.

QUERY_SNA_NET

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: State Check

Returned Parameters: Other Conditions