mrd_map_element - Map an absolute element address to a zero
    relative one.

    Windows NT         mrd.dll
    UNIX               /usr/lib/libmrd.a
    OpenVMS            MRD$RTL.EXE

    #include <mrd_common.h>
    #include <mrd_message.h>

    int mrd_map_element(
        const robot_info_t *robot_info,
        const int           address,
        char               *result) ;

1  –  Parameters

    o  robot_info - This is the address of a robot_info_t structure
       initialized using mrd_startup(3mrd) or mrd_show(3mrd). This
       data structure contains the element starting address and
       counts for each type of element, which are needed to map an
       absolute element to the correct zero relative address and
       type.

    o  address - This is the absolute element address that is to be
       mapped.

    o  result - This is the address where the zero relative element
       address is to be written. Like other element addresses used
       by the Media Robot Driver Library, it is a character string. A
       character array of MRD_NAME_SIZE bytes should be used.

2  –  Description

    Given a robot_info_t structure and absolute element address,
    this routine figures out the corresponding element type and zero
    relative address. The relative address is formatted into the
    space provided by result and the element type is returned.

    A valid robot_info_t structure can be obtained by using mrd_
    startup(3mrd) or mrd_show(3mrd) to open the robot and fill in the
    robot_info_t structure.

    The SCSI-2 specification allows an absolute address of zero (0)
    to refer to a default transport, when a medium-changer has more
    than one. When handed zero as the absolute address, this routine
    will reflect this convention even if the particular medium-
    changer doesn't.

3  –  Example

    /*
     *   For the specified robot, walk through the remainder of
     *   argument list and have mrd_map_element(3mrd) convert
     *   each address to a relative element address and type.
     *
     *      mrd_map_element robot address [ address... ]
     */
    #ifndef   lint
    static   char   SccsId[] = "@(#)mrd_map_element.c   1.2 3/5/97" ;
    #endif

    #include <stdio.h>
    #include <stdlib.h>
    #include <mrd_common.h>
    #include <mrd_message.h>

    main(int argc, char *argv[])
    {
       char      *robot ;   /* Robot for command */
       int      status ;   /* status from mrd_startup(3mrd) */
       int      address ;   /* Input argument */
       int      type ;      /* element type */
       int      i ;      /* index counter */
       robot_info_t   robot_info ;   /* Set by mrd_startup(3mrd) */
       char      result[MRD_NAME_SIZE+1] ;   /* relative address */
       char      log_info[MRD_MAX_LOG_STRING+1] ;   /* error text */

       /*
        *   Two required arguments, many optional ones.
        */
       if( argc < 3 ) {
          printf("usage: %s robot address [ address... ]\n", argv[0]) ;
          exit(1) ;
       }
       else
          robot = argv[1] ;

       /*
        *   Open the robot.  Must set channel to BAD_CHANNEL so
        *   it will really open the robot.
        */
       robot_info.channel = BAD_CHANNEL ;

       status = mrd_startup(robot, &robot_info, log_info) ;

       if( status != MRD_STATUS_SUCCESS ) {
          printf("Can't open robot %s: %s: %s.\n", robot,
             mrd_strstatus(status),
             log_info[0] ? log_info : "none") ;

          exit(1) ;
       }

       /*
        *   We don't need to keep the robot for the remainder of
        *   the example.
        */
       (void)mrd_shutdown(&robot_info) ;

       /*
        *   For each address in the list, call mrd_map_element(3mrd).
        */
       for(i = 2; i < argc; i++) {
          address = atoi(argv[i]) ;

          type = mrd_map_element(&robot_info, address, result) ;

          if( type == 0 )
             printf("Can't map %d on robot %s.\n", address, robot) ;
          else
             printf("Element %d -> %s %s\n", address,
                mrd_strelement(type), result) ;
       }

       return 0 ;
    }

4  –  Return Values

    Upon successful completion, the mrd_map_element(3mrd) function
    returns the element type, which is one of SLOT, PORT, DRIVE or
    TRANSPORT. On an error it returns zero (0). The two possible
    errors are the robot_info address being NULL and the address not
    one used by this medium-changer.

5  –  Related Functions

    Functions:

    o  mrd_show(3mrd)

    o  mrd_home(3mrd)

    o  mrd_find_cartridge(3mrd)