VMS Help System Services, $DISPLAY PROXY  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Returns information about one or more existing proxies.

    Format

      SYS$DISPLAY_PROXY  rem_node ,rem_user ,buffer_sizes ,proxy_node

                         ,proxy_user ,default_user ,local_users

                         ,flags ,[context]

    C Prototype

      int sys$display_proxy  (void *rem_node, void *rem_user,

                             unsigned short int buffer_sizes [4],

                             void *proxy_node, void *proxy_user,

                             void *default_user, unsigned int

                             *local_users, unsigned int flags,

                             unsigned int *context);

1 - Arguments

 rem_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote node name of the proxy about which information is being
    requested. The rem_node argument is the address of a character-
    string descriptor pointing to the remote node name string.

    A remote node name consists of 1 to 1024 characters. No specific
    characters, format, or case are required for a remote node
    name string. All node names are converted to their DECnet full
    name unless the PRX$M_BYPASS_EXPAND flag is set with the flags
    argument.

    Asterisk (*)  and percent sign (%) wildcards are allowed for the
    remote node specification. If you specify wildcards for the rem_
    node argument, the server searches the entire proxy database for
    matches to the remote node and remote user you specified. If a
    match is found, information about the matched proxy is returned.

    Refer to the OpenVMS System Services Reference Manual for
    additional details on retrieving information about multiple
    proxies.

 rem_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read only
    mechanism:    by descriptor-fixed-length string descriptor
    Remote user name of the proxy about which information is being
    requested. The rem_user argument is the address of a character-
    string descriptor pointing to the user name string.

    A remote user name consists of 1 to 32 alphanumeric characters,
    including dollar signs ($),  underscores (_), and brackets
    ([ ]).  Any lowercase characters specified are automatically
    converted to uppercase.

    The rem_user argument can be specified in user identification
    code (UIC) format ([group, member]).  Brackets are allowed only
    if the remote user name string specifies a UIC. Group and member
    are character-string representations of octal numbers with no
    leading zeros.

    Asterisk (*)  and percent sign (%) wildcards are allowed for the
    remote user specification. If you specify wildcards for the rem_
    user argument, the server searches the entire proxy database for
    matches to the remote node and remote user you specified. If a
    match is found, information about the matched proxy is returned.
    See the Description section for information about retrieving
    information about multiple proxies.

 buffer_sizes

    OpenVMS usage:return length block
    type:         array of 4 words (unsigned)
    access:       write only
    mechanism:    by reference
    Array of return lengths for various input buffers.

    Refer to the OpenVMS System Services Reference Manual to view the
    array diagram and buffer_sizes fields table.

 proxy_node

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Node name of a proxy matching the remote node name specified by
    the rem_node argument and the remote user name specified by the
    rem_user argument. The proxy_node argument is the address of a
    character-string descriptor pointing to a buffer to receive the
    proxy node name.

    The descriptor's buffer must be 1024 bytes long to receive a node
    name. The length of the returned node name is specified by the
    proxy node length field returned in the buffer specified by the
    buffer_sizes argument.

 proxy_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    User name of a proxy matching the remote node name specified by
    the rem_node argument and the remote user name specified by the
    rem_user argument. The proxy_user argument is a character-string
    descriptor pointing to a buffer to receive the remote user name
    of a proxy.

    The descriptor's buffer must be 32 bytes long to receive a user
    name. The length of the returned user name is specified by the
    proxy user length field returned in the buffer specified by the
    buffer_sizes argument.

 default_user

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       write only
    mechanism:    by descriptor-fixed-length string descriptor
    Default user of a proxy matching the node name specified by the
    rem_node argument and the remote user name specified by the rem_
    user argument. The default_user argument is the address of a
    character-string descriptor pointing to a buffer to receive the
    default user name.

    The descriptor's buffer must be 32 bytes long to receive a user
    name. The length of the returned user name is specified in the
    default user length field in the buffer specified by the buffer_
    sizes argument.

 local_users

    OpenVMS usage:buffer
    type:         array of 0 to 16 user name buffers
    access:       write only
    mechanism:    by reference
    Array of local user names associated with a proxy matching the
    remote node name specified by the rem_node argument and the
    remote user name specified by the rem_user argument. The local_
    users argument is the address of a buffer to receive an array of
    local user names.

    Refer to the OpenVMS System Services Reference Manual to view the
    array diagram and local_users fields table.

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Functional specification for the service and type of user the
    local_user argument represents. The flags argument is a longword
    bit mask wherein each bit corresponds to an option.

    Each flag option has a symbolic name. The $PRXDEF macro defines
    the following symbolic names:

    Symbolic Name      Description

    PRX$M_BYPASS_      The service should not convert the node name
    EXPAND             specified in the rem_node argument to its
                       corresponding DECnet full name. If this flag
                       is set, it is the caller's responsibility to
                       ensure that the fully expanded node name is
                       passed into the service.

    PRX$M_EXACT        The service should match exactly the remote
                       node and remote user and ignore wildcards.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference
    Context information to keep between related calls to the
    $DISPLAY_PROXY service. The context argument is the address of
    a longword to receive a context from the $DISPLAY_PROXY service.

    The initial value contained in the longword pointed to by the
    context argument must be 0. The contents of the unsigned longword
    must not be changed after the service has set its value. If the
    contents of the buffer pointed to by the context argument are
    changed between calls to the $DISPLAY_PROXY service, the service
    will return SS$_BADCONTEXT. If the contents of the context
    argument are changed between calls to the $DISPLAY_PROXY service,
    you can change the value of the context argument back to 0 to
    start the search over again.

    Contexts become invalid after one-half hour of non-use. This
    means that if you call the $DISPLAY_PROXY service with a wildcard
    rem_node or rem_user, and do not call the service to get the
    next matching record within one-half hour, the context becomes
    invalid. If the context has become invalid, you must start your
    search of the proxy database over from its beginning by resetting
    the context to 0.