prf_get_sites()

PRF_$GET_SITES                    Domain/OS                     PRF_$GET_SITES


NAME
     prf_$get_sites - get a list of print sites

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/prf.h>

     void prf_$get_sites(
          long *index,
          long &max_sites,
          long *ret_sites,
          prf_$name_t *site_list,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/prf.ins.pas';

     procedure prf_$get_sites(
          var index: integer32;
          in max_sites: integer32;
          out ret_sites: integer32;
          out site_list: univ prf_$name_array_t;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'

           integer*2 n_sites, example
           parameter (n_sites = 32, example = 3)

           integer*4 index, max_sites, ret_sites, status
           character site_list(n_sites)*34

           integer*2 site_location_length
           character site_location*32

           equivalence (site_location, site_list(example))
           equivalence (site_location_length, site_list(example) (33:34))

           call prf_$get_sites(index, max_sites, ret_sites, site_list, status)

DESCRIPTION
     This call supplies the locations of up to max_sites print sites on the
     network.  The index argument passed to prf_$get_sites controls which por-
     tion of the network site list is supplied in site_list.

     index
          An index into the list of sites supplied by prf_$get_sites.  Index
          specifies the position in the network site list of the first site
          requested when prf_$get_sites is called; it contains the position in
          the list of the next site to request when prf_$get_sites returns.

          When calling prf_$get_sites, an index of 1 will cause prf_$get_sites
          to supply the first max_sites site locations.  Then when
          prf_$get_sites returns, index will be the position of the next
          unread site location in the list.

          If the difference between the call and return values of index is
          less than max_sites, then site_list contains the location of the
          last site in the network site list.  If the difference is equal to
          max_sites, there may be more sites on the network; that is,
          site_list may not contain the location of the last print site in the
          site list.  If the site list is exhausted when prf_$get_sites
          returns, index contains the position of the last site, or, more sim-
          ply, just the number of sites on the network.

     max_sites
          The maximum number of sites that prf_$get_sites should supply.  The
          value of max_sites depends on the size of the buffer allocated to
          receive the site_list argument.

     ret_sites
          The number of sites supplied in site_list.

     site_list
          An array of type prf_$name_t containing a list of sites.  Each ele-
          ment of the array is a string containing the site's location fol-
          lowed by the number of bytes in the string.

     status
          The completion status.

SEE ALSO
     prf_$get_printers.
Museum
