Traduccin al Castellano del fichero USRLIB.DOC original en Ingls
N.T.> Significa Nota del Traductor





               Instrucciones para el programa MS-DOS "USRLIB" 

       *****************************************************************

                                     AVISO

      Hewlett-Packard pone a disposicin de los clientes la versin
      preliminar actual 2.2 de USRLIB.EXE sin coste alguno para ayudarles en
      el desarrollo de aplicaciones para la HP 48SX con las siguientes
      condiciones.

      N.T.>Se dejan los trminos legales en su versin original en Ingls.

       * The program USRLIB.EXE and the documentation file USRLIB.MAN are
       provided "as is," and are subject to change without notice.
       Hewlett-Packard Company make no warranty of any kind with regard
       to the software or documentation, including, but not limited to,
       the implied warranties of merchantability and fitness for a
       particular purpose.  Hewlett-Packard Company shall not be liable
       for any error or for incidental or consequential damages in
       connection with the furnishing, performance, or use of this
       software and documentation.

       * The program and documentation are copyrighted by Hewlett-
       Packard.  Customers may freely reproduce and distribute this
       material.  Sale of this material is prohibited without prior
       written permission of Hewlett-Packard Company.

       * The HP Customer Support department does not support the current
       version.  Questions, comments, defect reports, etc. should be
       directed to the Library Development conference on the HP
       Calculator Bulletin Board System.  All responses from Hewlett-
       Packard will normally be provided through that conference.

       * Software converted into libraries by USRLIB.EXE should be tested
       and qualified in its library form.  Discrepancies between the
       execution of the libraries and the execution of the original
       source directory contents should be reported via the Bulletin
       Board.

      Las versiones revisadas del software y la documentacin se pondrn en
      la BBS en cuanto estn disponibles. En particular, las versiones
      futuras incluirn mensajes de error menos crpticos y una mejor
      documentacin de la informacin de los listados de salida
      proporcionados por el programa.

      La versin 2.2 del programa USRLIB.EXE es una versin preliminar de
      este software. El software que se compile en bibliotecas usando este
      programa debera comprobarse en profundidad en su forma de biblioteca
      antes de cualquier reproduccin o distribucin a los usuarios finales.

       *****************************************************************










                                   -1-











      1. INTRODUCCION


      USRLIB.EXE es un fichero MS-DOS ejecutable que crea un objeto
      biblioteca de la HP 48 a partir de un directorio de la HP 48. Una
      biblioteca se parece a un directorio en que ambos son una coleccin de
      objetos con nombre. Sin embargo, un directorio reside normalmente en la
      memoria RAM principal y est pensado para una modificacin y ejecucin
      continuas, mientras que una biblioteca contiene objetos pensados solo
      para ejecutarse y que se pueden usar desde ROM tan fcilmente como
      desde RAM. Los objetos de un directorio se organizan en una lista
      encadenada que requiere una bsqueda secuencial para su acceso; una
      biblioteca contiene una tabla de direcciones que proporciona un acceso
      rpido de sus objetos individuales.


      1.1   Glosario de Trminos

      Directorio           Un objeto directorio de la HP 48 que contiene cero
                           o ms variables.

      Variable             Un objeto con nombre contenido dentro de un
                           directorio al que se accede mediante un nombre
                           global.

      Biblioteca           Un objeto biblioteca de la HP 48 que contiene cero
                           o ms comandos de biblioteca. Las bibliotecas
                           incluyen un texto de ttulo, un nmero ID de
                           Biblioteca, tablas de mensajes opcionales y cdigo
                           de configuracin opcional que se ejecuta en las
                           paradas del sistema.

      Comando de Biblioteca
                           Un objeto con nombre dentro de una biblioteca, que
                           para una biblioteca es el anlogo de una variable
                           de directorio.

      Nombre Global        Un objeto nombre global de la HP 48, la ejecucin
                           del cual ejecuta el objeto en la correspondiente
                           variable (global).

      Nombre XLIB          Un objeto nombre XLIB de la HP 48, la ejecucin
                           del cual ejecuta el comando de biblioteca
                           correspondiente. Un nombre XLIB representa para
                           las bibliotecas el papel que un nombre global
                           representa para los directorios.

      ID de Biblioteca     Un nmero en el margen 0-7FFh que identifica de
                           manera nica a una biblioteca y se usa como el
                           argumento de los comandos HP 48 que tratan con
                           bibliotecas como objetos. Se definen los
                           siguientes mrgenes para los nmeros ID:







                                   -2-











                        Margen ID           Propsito
                    Hex        Decimal
 
                   0 - 100       0 - 256
                 101 - 200     257 - 512   Aplicaciones HP Basadas en ROM 
                 201 - 300     513 - 768   Aplicaciones HP Basadas en RAM
                 301 - 600    769 - 1536   Aplicaciones NO-HP
                                           (nmeros asignados de modo
                                            permanente por HP)
                 601 - 6FF   1537 - 1792
                 700 - 7FF   1792 - 2047   Usados por la Lnea de Comandos de
                                           la HP 48SX



      1.2   El Directorio Fuente

      USRLIB usa un objeto directorio de la HP 48 como el fichero fuente para
      definir la biblioteca de salida. El directorio fuente puede contener
      cualquier nmero de variables, cada una de las cuales se convierte en
      un comando de biblioteca en la biblioteca de salida (a menos que se
      especifique lo contrario; ver $VARS, $VISIBLE y $HIDDEN ms abajo). Los
      objetos en las variables se traducen como sea necesario de modo que
      cualquier nombre global en los objetos que corresponden a variables en
      el directorio fuente se convierten a nombres XLIB.

      El directorio fuente puede contener subdirectorios pero, en ese caso,
      la biblioteca resultante no reflejar la estructura del directorio ya
      que la estructura de una biblioteca es "plana". Si subdirectorios
      diferentes contienen variables con el mismo nombre, el uso de esos
      nombres dentro de la biblioteca ser correcto pero los nombres
      duplicados tambin se duplicarn en el men de la BIBLIOTECA. Los
      nombres de los subdirectorios mismos no se traducen en comandos de la
      biblioteca y cualquier uso de esos nombres en cualquiera de las otras
      variables darn lugar a un error durante la ejecucin de USRLIB.

      El directorio tambin puede incluir las siguientes variables
      especiales:


      $ROMID      Contiene un objeto nmero real o binario que representa el
                  ID de Biblioteca que se dar a la biblioteca. Se puede
                  pasar por encima de la variable especificando ``-r idrom''
                  en la lnea de comandos. El ID debera estar en el margen
                  769 - 1792 (301h - 6FFh).

                  En la lnea de comandos se tiene que especificar la
                  opcin -r si no se ha usado ninguna $ROMID

      $TITLE      Contiene la cadena de caracteres que se usar como el
                  nombre de la biblioteca. Se puede pasar por encima de la
                  variable especificando ``-t ttulo'' en la lnea de
                  comandos. Se usan (hasta) los primeros 5 caracteres del
                  ttulo para la etiqueta de men de la BIBLIOTECA; REVIEW
                  muestra los primeros 22 caracteres




                                   -3-





      $CONFIG     Contiene el objeto que se ejecutar en la configuracin. Si
                  no hay presente ninguna variable $CONFIG, no se generar
                  ninguna entrada de configuracin. En la versin actual de
                  USRLIB, $CONFIG se traduce tambin a un comando de la
                  biblioteca; para evitar esto, se debera declarar $CONFIG
                  como oculta (ver ms abajo).

                  Nota: Generalmente, el cdigo de configuracin puede estar
                  escrito en comandos no accesibles al usuario. Programas
                  sencillos como << 123 ATTACH >> estn bien pero los
                  programas ms complicados deben vigilar de no cambiar la
                  pila y estar seguros de NO PRODUCIR ERRORES.

      $MESSAGE    Contiene una lista de nombres de variables que contienen
                  cadenas de caracteres que se combinarn en una tabla de
                  mensajes. Los nmeros de mensaje corresponden a las
                  posiciones en la lista.

                  Si no hay ningn $MESSAGE presente, no se generar ninguna
                  tabla de mensajes.

      $VISIBLE    Contiene una lista de nombres de variables que se
                  convertirn en comandos de biblioteca accesibles al
                  usuario.

                  Por defecto, se traducirn todas las variables a comandos
                  de biblioteca. Cuando la lista $VISIBLE est presente, solo
                  los nombres en esta lista se usan como entradas de la tabla
                  de nombres XLIB en la biblioteca. Se permite una lista
                  vaca, lo que significa que no se crear ninguna entrada de
                  nombre XLIB.

      $HIDDEN     Contiene una lista de nombres de variables que se
                  convertirn en objetos con nombres nulos en la biblioteca
                  y, por consiguiente, ocultas al usuario de la biblioteca.

                  Cuando est presente la lista $HIDDEN, aquellos nombres
                  listados no se introducen en la tabla de nombres XLIB de la
                  biblioteca. Si estn presentes tanto $VISIBLE como $HIDDEN,
                  solo se usar la lista $HIDDEN.

      $VARS       Contiene una lista de variables que permanecern basadas en
                  RAM, o sea, los objetos almacenados en ellas no se
                  incluirn en la biblioteca y no se hacen entradas de nombre
                  XLIB para sus nombres. Todas las dems variables en el
                  directorio fuente se incluyen como comandos de biblioteca.


      Se permiten varias apariciones de las variables de declaracin $VARS,
      $HIDDEN y $VISIBLE en varios subdirectorios del directorio fuente. Una
      variable se declara variable RAM, oculta, etc. si se incluye su nombre
      en cualquiera de las variables de declaracin relevantes en cualquier
      sitio de la ruta (path) actual definida por la ubicacin de la
      variable. Esto es, una variable XXX que se encuentra en cualquier
      subdirectorio ser ocultada si XXX est en una lista almacenada en
      $HIDDEN en el nivel ms alto del directorio fuente; pero YYY en el
      nivel ms alto no ser ocultada aunque YYY est presente en la lista de
      un $HIDDEN en un subdirectorio.







                                   -4-






      No todos los objetos programa que se ejecutan correctamente desde
      variables globales se pueden convertir directamente en bibliotecas. En
      general, no se pueden hacer comprobaciones de tales errores y USRLIB ni
      lo intenta. He aqu algunos problemas conocidos:

         +  Como quiera que una biblioteca no se puede modificar, ningn
            comando de biblioteca puede ser el objetivo de una operacin STO
            o PUT.

         +  No se pueden usar los nombres XLIB en todos los contextos en los
            que los nombres globales son argumentos vlidos. Esto puede
            provocar que construcciones que referencian un objeto con nombre
            fallen. Por ejemplo

                                      'A' 5 GETI

            donde A es una lista no funcionar cuando A se convierte en un
            nombre XLIB. Usar en su lugar

                                   'A' EVAL 5 GETI

            o mejor an

                                      A 5 GETI

            Los nombres XLIB no son vlidos como variables formales en
            algebraicos o como variable independiente en el trazado o la
            resolucin (Plot/Solve). Los nombres pensados para usarse como
            tales se deberan declarar como globales usando $VARS o la opcin
            -v.

         +  ->STR aplicado a un nombre global que se ha convertido en un
            comando de biblioteca ``oculto'' (ver $HIDDEN) devuelve una
            cadena de caracteres nula.

         +  De los directorios embebidos (introducidos como DIR...END) dentro
            de listas y programas solo se traduce su primer objeto.



























                                   -5-











      1.3   Creacin de Bibliotecas

      El proceso de creacin y activacin de una biblioteca se puede resumir
      as.

         1. Desarrolla una aplicacin que consista en cualquier nmero de
            programas y otros objetos y renelos en un directorio de un solo
            nivel en la HP 48.

         2. Usando el modo de transferencia binario del Kermit, enva el
            directorio al PC.

         3. Ejecuta USRLIB usando el directorio como el fichero fuente. En
            este paso, tambin asignas un ID de biblioteca y un ttulo de
            biblioteca a la biblioteca generada.

         4. Transfiere el objeto biblioteca generado por USRLIB a la HP 48, a
            una variable en cualquier directorio conveniente.

         5. Llama al objeto biblioteca desde la variable a la que fue
            transferido y almacnalo en un puerto RAM (:n:x STO, donde n es
            el nmero del puerto y x es cualquier nmero). Despus de
            almacenar la biblioteca, puedes borrar la copia original en la
            variable para ahorrar memoria.

         6. Apaga la HP 48 y luego encindela. Con esto se aade la nueva
            biblioteca a la tabla se bibliotecas del sistema y le da a la
            biblioteca la oportunidad de ejecutar su propio programa de
            configuracin, si lo tiene. (La HP 48 ejecutar automticamente,
            en este punto, una parada del sistema por lo que deberas
            almacenar primero cualquier objeto de la pila o el PICT si los
            deseas recuperar.) El men LIBRARY contendr ahora una entrada de
            men etiquetada con el nmero de ID de la biblioteca en el
            submen PORTn.

         7. Activa el directorio en el que deseas que sean accesibles los
            comandos de la biblioteca y ejecuta entonces nnn ATTACH, donde
            nnn es el ID de la biblioteca. Se puede unir (attach) cualquier
            nmero de bibliotecas al directorio HOME; los subdirectorios solo
            pueden tener una biblioteca unida a cada uno de ellos. El men
            principal LIBRARY contendr ahora un tecla de men etiquetada con
            el ttulo de la biblioteca.

      Para eliminar una biblioteca, activa su directorio asociado y ejecuta
      nnn DETACH. Luego ejecuta :n:ID PURGE para eliminar la biblioteca del
      puerto n. (Notars un pequeo salto en la pantalla cuando ejecutes el
      PURGE. Esto es normal e inofensivo)












                                   -6-











      2. Instrucciones

      (el texto entre ngulos (<>) representa texto suministrado por el
      usuario. El texto que aparece entre corchetes ([]) denota entradas
      opcionales. En las entradas reales, no se deben usar estos corchetes ni
      ngulos).

      Sintaxis:

         USRLIB [-opciones] <fich_dir> [ <fich_lib> [ <fich_sum> ] ] 

         <fich_dir>  es el nombre del fichero fuente, que debe contener una
                     imagen binaria de un directorio HP48 o un objeto backup
                     que contenga un directorio.

         <fich_lib>  es el fichero que contendr el objeto biblioteca
                     generado

         <fich_sum>  Es un resumen textual de los nombres que se tradujeron.
                     Se da la siguiente informacin de cada objeto: nombre de
                     usuario, tipo, offset dentro del fichero <fich_lib>,
                     nmeros XLIB, si se puede usar en un algebraico y si es
                     visible.

                     De modo similar, se da una lista con los nmeros de
                     mensajes y los mensajes y un resumen de los
                     requerimientos de espacio.

         <fich_sum> y el <fich_list> opcional (ver OPCIONES ms abajo) se
         pueden redireccionar a la salida_estndar usando '-' como nombre del
         fichero de salida.


      2.1   Opciones

      Se pueden incluir las siguientes opciones en la lnea de comandos de
      USRLIB:


      -d <fich_list> <fich_list> contendr un listado de texto con los
                     contenidos de cada objeto en el directorio de entrada.

      -h <cabecera>  Usa <cabecera> como la cabecera del objeto biblioteca
                     (para la transferencia de ficheros).

      -l <fich_list> <fich_list> contendr un listado de texto con los
                     contenidos de cada objeto en la biblioteca de salida. La
                     presencia de "ID'nombre'<--" indica la traduccin de un
                     nombre (ID) a un XLIB o una referencia de la tabla de
                     mensajes.

      -r <idrom>     Pone el ID de Biblioteca decimal (ver $ROMID ms
                     arriba).






                                   -7-










      -t <ttulo>    Usa <ttulo> como el ttulo de la biblioteca (ver $TITLE
                     ms arriba).

      -v <nombre>    Declara <nombre> como el nombre de una variable RAM (ver
                     $VARS arriba)


      2.2   Restricciones

         1. El fichero generado de biblioteca no puede ser mayor en total de
            128K bytes.

         2. Las cadenas de caracteres de los mensajes deben ser menores de
            64K bytes cada una.


      2.3   Ejemplo

      El siguiente ejemplo combina los programas PAD, PRESERVE y una versin
      modificada de BDISP del Manual del Propietario en una aplicacin de
      biblioteca.

      Las variables $TITLE, $ROMID, $VISIBLE y $VARS controlan la creacin de
      la biblioteca. La variable $CONFIG contiene un programa que une la
      biblioteca al directorio HOME en cuanto se produzca una Parada del
      Sistema.

      BDISP se ha modificado para almacenar en la variable LSTN la versin
      hex del nmero entrado. La variable $VARS especifica que LSTN ser una
      variable de usuario (estar en el men VAR) y que no se debe compilar
      en la biblioteca.

      BDIPS llama a los programas PAD y PRESERVE. Ya que la variable de
      control $VISIBLE solo especifica BDISP, todas las dems variables
      estarn ocultas (o dejadas como globales como especifique la variable
      $VARS).
























                                   -8-











      En formato ASCII, un directorio que contiene todo lo que se requiere
      para la aplicacin de biblioteca completa se vera as:

       %%HP: T(3)A(D)F(.);
       DIR
         PRESERVE
           << RCLF -> f
             << EVAL f STOF >>
           >>
         PAD
           << ->STR
             WHILE
               DUP SIZE 22 <
             REPEAT
               " " SWAP +
             END
           >>
         BDISP
           <<
             << DUP -55 CF
               IFERR R->B
               THEN
               END -> n
               << CLLCD
                 << BIN >>
                 << OCT >>
                 << DEC >>
                 << HEX >>
                 1 4
                 FOR j
                   EVAL n ->STR PAD
                   j DISP
                 NEXT n 'LSTN' STO
               >> 3 FREEZE
             >> PRESERVE
           >>
         $CONFIG  << HOME 800 ATTACH >>
         $ROMID   800
         $TITLE   "BDLIB :Binary Display"
         $VISIBLE { BDISP }
         $VARS    { LSTN }
       END

















                                   -9-
      2.4   Mensajes de Error

      En los mensajes de error siguientes, las palabras mostradas entre
      parntesis representan valores que indican cantidades especficas del
      fuente. (path) representa la ruta dentro del directorio fuente a la
      variable que provoca el error, de la forma nombre1/nombre2/..., donde
      los nombres son los nombres de los subdirectorios (en la HP 48SX, la
      ruta sera una lista { nombre1 nombre2 ... }).

         "Insufficient Memory"
         "Memoria Insuficiente"
                  -  La memoria est siendo asignada constantemente para
                     varias necesidades del compilador.

         "Unexpected EOF on Input" 
         "EOF Inesperado durante la Entrada"
                  -  Se ha encontrado un EOF (End_Of_File) (Fin_De_Fichero)
                     cuando se esperaban ms nibbles.

         "USRLIB: Cannot open"
         "USRLIB: No se puede abrir"
                  -  No se puede abrir el fichero fuente

         "USRLIB: - not legal for input"
         "USRLIB: - ilegal en la entrada"
                  -  "-" (entrada_estndar) no se puede usar en la entrada.

         "ROMID must be in range 769 - 1792"
         "ROMID debe estar dentro del margen 769 - 1792"

         "Must have either -r romid or $ROMID"
         "Debe haber -r idrom o $ROMID"
                  -  No se especific ningn ID de biblioteca.

         "Need either BAK of a directory or a directory"
         "Se necesita o un BAK o un directorio"
         N.T.> BAK = Backup

         "BAK object does not contain directory"
         "El BAK no contiene un directorio"

         "Directory is empty"
         "El directorio est vaco"

         "Object is not a string: (path)/$TITLE"
         "El objeto no es una cadena de caracteres: (ruta)/$TITLE"

      Los tres siguientes mensajes pueden darse cuando se especifica el ROMID
      en la variable $ROMID.

         "Illegal Real value for (path)/$ROMID: (value)"
         "Valor Real Ilegal para (ruta)/$ROMID: (valor)"

         "Illegal Binary value for (path)/$ROMID: (value)"
         "Valor Binario Ilegal para (ruta)/$ROMID (valor)"

         "Object not Real or Binary: (path)/$ROMID"
         "El Objeto no es ni Real ni Binario: (ruta)/$ROMID"

      Los dos siguientes mensajes se pueden dar cuando se especifica una
      variable $CONFIG (o dos).

         "Object not program: (path)/$CONFIG"
         "El Objeto no es un programa: (ruta)/$CONFIG"

         "$CONFIG redefined: (path)/$CONFIG"
         "Redefinido el $CONFIG: (ruta)/$CONFIG"


                                   -10-



      El siguiente mensaje se puede dar cada vez que se lee una cadena de
      caracteres (nombre de variable o mensaje)

         "Variable name or message too long (>65535)"
         "Nombre de la variable o mensaje demasiado largo (>65535)"

      Los dos siguientes mensajes pueden darse cuando se lee una lista de
      nombres. Las variables $MESSAGE, $VISIBLE, $HIDDEN y $VARS son todas
      listas de nombres.

         "Object is not a list: (path)/name"
         "El Objeto no es una lista: (ruta)/nombre"

         "Non-ID found in list:  (path)/name"
         "Se ha encontrado en la lista algo que no es un ID: (ruta)/nombre"

         "Message object not found: (name)"
         "No se ha encontrado el objeto mensaje: (nombre)"

         "Loss of object synchronism between passes: (path)/(name)"
         "Prdida del sincronismo de objeto entre pases: (ruta)/(nombre)"
            -  (ruta)/(nombre) se reemplaza con el objeto donde se descubri
               el fuera_de_sincronismo.

         "Name must not exceed 16 characters: (path)/(name)"
         "El nombre no puede exceder de 16 caracteres: (ruta)/(nombre)"
            -  Los nombres de los objetos biblioteca estn limitados a 16
               caracteres.

         "Keyword cannot resolve to a directory: (path)/(name)"
         "La palabra_clave no se puede resolver a un directorio:
         (ruta)/(nombre)"
            -  Los nombres de subdirectorios no se pueden incluir en las
               definiciones de otros objetos directorio.

      Los dos siguientes mensajes se pueden dar mientras los objetos mensajes
      (indicados en la lista $MESSAGE) se estn convirtiendo en una tabla de
      mensajes.

         "Message object is not a string: (path)/(name)"
         "El objeto mensaje no es una cadena de caracteres: (ruta)/(nombre)"

         "Multiple definitions for message (path)/(name)"
         "Definiciones mltiples del mensaje (ruta)/(nombre)"

      Los tres mensajes siguientes se pueden dar mientras se est escribiendo
      el objeto biblioteca  final en el fichero de salida.

         "Library image length is 0.  LIB FILE NOT WRITTEN!"
         "La longitud de la imagen de la biblioteca es 0. NO SE HA ESCRITO EL
         FICHERO BIBLIOTECA"

         "Max image size is 256K nibbles ... image is (value) nibbles.
          LIB FILE NOT WRITTEN!"
         "El tamao mximo de la imagen es de 256K nibbles ... la imagen
         tiene (valor) nibbles. NO SE ESCRITO EL FICHERO BIBLIOTECA"

         "Unsucessful write to library file"
         "Escritura fallida en el fichero biblioteca "
            -  Error desconocido escribiendo en el fichero biblioteca.

   





                                   -11-