
 ۻ   ۻ  ۻ      RAR versin 2.02
 ۻ ۻ ۻ     ~~~~~~~~~~~~~~~~
 ɼ ۺ ɼ     Administrador Multifuncin de Compresin
 ۻ ۺ ۻ     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ۺ  ۺ ۺ  ۺ ۺ  ۺ     Manual de Usuario del
 ͼ  ͼ ͼ  ͼ ͼ  ͼ     ~~~~~~~~~~~~~~~~~~~~~
				Mdulo SFX de Instalacin para DOS
				~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   1. Descripcin de las funciones del mdulo SFX

   El mdulo SFX es la parte del archivo auto-extrable que se encarga
   de extraer los ficheros cuando se ejecuta. Tiene la apariencia de
   un fichero ejecutable normal.

   El compresor RAR ofrece la funcionalidad SFX de forma significativa-
   mente mejorada respecto a los SFX normales, asi como la posibilidad
   de crear un archivo SFX con un mdulo SFX alternativo.

   Puede crear un archivo SFX con un mdulo alternativo con la opcin
   '-sfx[<moduloSFX>]' o la orden 's[<moduloSFX>]' si le indica, en el
   parmetro opcional <moduloSFX>, el mdulo SFX que desea.

   Actualmente, puede usar varios mdulos SFX RAR:

      - mdulo normal para DOS (usado por defecto en la versin DOS,
	fichero dos.sfx);
      - mdulo de instalacin para DOS (fichero idos.sfx);
      - mdulo normal para OS/2 (usado por defecto en la versin
	para OS/2, fichero os2.sfx).

   De hecho, usted puede aadir sus propios mdulos SFX usando el
   cdigo fuente de unRAR (por ejemplo, para sussistema operativo
   o necesidades especiales).


   2. El mdulo SFX de Instalacin.

   Como alternativa al mdulo SFX normal, usted puede usar el mdulo
   SFX de instalacin, que usa un potente lenguaje script para propor-
   cionar nuevas funcionalidades:

     - interface de mens completamente configurable;
     - comprobacin de espacio libre en disco antes de instalar;
     - pregunta por el directorio donde instalar los ficheros;
     - estado de la instalacin - barra brfica de descompresin,
       tanto por ciento completado y otras funciones.

   El script de Instalacin es un fichero ASCII normal, que puede ser
   preparado con su editor de textos favorito. El script se aade como
   comentario al archivo SFX deseado para que sea procesado por el mdulo
   SFX de Instalacin al ejecutarse. Por ejemplo, use las siguientes
   instrucciones para crear un archivo SFX de este tipo:

     rar a -sfxidos.sfx -zmyinst.s minstall

   Donde 'idos.sfx' es la trayectoria del mdulo SFX de Instalacin y
   el fichero 'myinst.s' es el fichero de texto que contiene el script
   de instalacin.

   El mdulo SFX de Instalacin contiene el interprete del Lenguaje
   Script.


   2.1 El Lenguaje Script de Instalacin

   Como en cualquier lenguaje de programacin, el script contiene los
   siguientes objetos:

     Orden          sentencia que inicia una accin;

     Procedimiento  ordenes definidas para ser llamadas desde el
		    cdigo principal del script;

     Funcin        procedimiento interno que devuelve un valor;

     Constante      cadena de carcteres o valor numrico (4 bytes);

     Variable       nombre que define donde se guarda un valor.

   A las variables se les puede asignar tanto una cadena de carcteres
   como un valor numrico. Todas las variables son globales, es decir,
   una vez definidas son iguales y conocidas tanto en el cdigo principal
   como en todos los procedimientos.

   Las variables y los procedimientos distinguen maysculas de minsculas.
   Las ordenes no distinguren maysculas de minsculas.

   Las ordenes y los procedimientos internos pueden ser llamados con
   parmetros - constantes y variables, sin embargo, no puede usar
   expresiones como parmetros.


   2.1.1. Ordenes de Control


   CALL        Llamar a un procedimiento:

	       CALL <NombreProc>

	       <NombreProc> es el identificador del procedimiento
	       (definido con PROC).


   DELAY       Suspender la ejecucin del script:

	       DELAY [<ms>]

	       <ms> es el retardo en milisegundos. Si se omite el valor
	       del intervalo se producira un retardo infinito que slo
	       puede ser cancelado al pulsar una tecla o un botn del
	       ratn.


   EXCLUDE     Define la lista de ficheros que NO sern extrados del
	       archivo en el procedimiento de instalacin.

	       EXCLUDE [ <Fichero1> [, <Fichero2>..] ]

	       <Fichero1>, <Fichero2>.. son las variables o cadenas de
	       carcteres que contienen los ficheros a excluir. Se
	       permiten comodines.

	       El valor inicial de esta lista es "", lo que significa
	       "no hay ficheros que excluir". EXCLUDE sin ningn
	       parmetro restaurar el valor inicial de la lista.


   EXIT        Finalizar el script de instalacin:

	       EXIT <Cdigo>

	       El mdulo SFX termina con el cdigo de salida = <Cdigo>.


   GOTO        Transfiere el control a una lnea del script identificada
	       por una etiqueta:

	       GOTO <Etiqueta>

	       <Etiqueta> es el identificador seguido por el carcter ':'.
	       Por ejemplo:

	       GOTO Menu
	       ...
	       Menu:


   IF          Ejecucin condicional de ordenes:

	       IF <Var> <?> <Valr>
		     <ordenes>
		     ...
	       ENDIF

	       Orden de control de flujo que define la ejecucin condicional
	       de las ordenes contenidas es la extructura IF...ENDIF.
	       <Var> es la variable que se compara con <Valor> usando un
	       slo operador de comparacin, si el resultado de la
	       comparacin es VERDADERO las ordenes contenidas en el
	       IF...ENDIF son ejecutadas.

	       Ls operadores de comparacin son:-

	       '=='  ..  IGUAL QUE
	       '!='  ..  DIFERENTE DE
	       '>'   ..  MAYOR QUE
	       '>='  ..  MAYOR O IGUAL QUE
	       '<'   ..  MENOR QUE
	       '<='  ..  MENOR O IGUAL QUE

	       <Valor> es una constante o una variable.
	       Las cadenas de carcteres slo pueden ser comparadas con
	       los operadores '==' o '!='.


   INCLUDE     Define la lista de ficheros a extraer del archivo en el
	       proceso de instalacin:

	       INCLUDE [ <Fichero1> [, <Fichero2>..] ]

	       <Fichero1>, <Fichero2>.. son variables o cadenas de
	       carcteres que contienen los nombres de fichero a
	       extraer. Se permiten comodines.

	       El valor inicial de esta lista es "*.*", lo que significa
	       "extraer todos ls ficheros del archivo". El primer INCLUDE
	       definido substituir el valor por defecto con el valor
	       especificado. Todos los INCLUDE siguientes aadirn nombres
	       de fichero a la lista sin borrar los valores anteriores.
	       Para eliminar todos los nombres de fichero de la lista,
	       puede incluir la orden INCLUDE sin ningn parmetro.


   INSTALL     Iniciar el proceso de instalacin. Si no se encuentra
	       ninguna orden INSTALL, la instalacin empezar cuando
	       se llegue al final del mdulo principal del script.


   OVERWRITE   Establece el modo de sobreescitura al extraer ficheros:

	       OVERWRITE { ON | OFF | FRESH | UPDATE }

	       ON      Siempre sobreescribir ficheros.
	       OFF     No sobreescribir ficheros nunca.
	       FRESH   Slo sobreescribe ficheros si el contenido
		       en el archivo es ms nuevo.
	       UPDATE  Igual que FRESH pero adems tambin extrae
		       los ficheros que no existan en el directorio
		       destino.


   PROC        Definir un procedimiento:

	       PROC <NombreProc>
		    <ordenes>
		    ...
	       ENDP

	       <NombreProc> es el nombre del procedimiento. Al ser
	       llamado por la orden CALL, las ordenes cntenidas
	       entre PROC y ENDP sern procesadas.


   SOUND       Produce un sonido en el altavoz del PC:

	       SOUND <F1>, <D1> [, <F2>, <D2>...]

	       <F1> es la frequncia y <D1> la duracin en milisegundos
	       del sonido producido. Puede incluir tantas notas como
	       desee.


   SYSTEM      Ejecutar una programa u orden del DOS:

	       SYSTEM <Arg1> [, <Arg2>..]

	       La lnea de comandos formada por <Arg1>, <Arg2> ...
	       es ejecutada.

   ;           Las cadenas que empiecen con el carcter ';' son
	       comentarios y sern ignoradas al procesarse.

   =           Para establecer el valor de una variable se puede usar
	       la expresin:

	       <Var>=<Expresion>

	       <Var> es el nombre de la variable y <Expresion> puede
	       ser una constante, expresin numrica o una llamada a
	       una funcin.

	       Una expresin numrica es la combinacin de ternas del
	       tipo "A # B", donde A y B pueden ser constantes numricas
	       y/o variables, '#' es uno de los siguientes operadores
	       matemticos : '+', '-', '*', '/', '%'.


   2.1.2. Ordenes de pantalla

   Toda la salida es dirigida a la ventana de texto actual (vea la
   descripcin de la orden WINDOW).

   El color del texto y de fondo se designan en todas las ordenes
   con palabras clave asociadas a cada color:

   BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY,
   LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW, WHITE.

   Tambin puede usar el valor numrico del atributo (de 0 a 15) para
   designar cada color.

   Si no se especifica el color de texto y fondo como parmetro en alguna
   orden, se usar el color actual (vea la orden SETCOLOR).


   BOX         Dibuja una caja:

	       BOX <X1>, <Y1>, <X2>, <Y2>, <Col>, <Bck>, SINGLE | DOUBLE

	       <X1>, <Y1> - las coordenadas del punto ms alto y a la
			    izquierda de la caja;
	       <X2>, <Y2> - las coordenadas del punto ms bajo y a la
			    derecha de la caja;
	       <Col>,
	       <Bck>      - el color del texto y del fondo;
	       SINGLE o
	       DOUBLE     - Tipo de marco, una o dos lneas.


   CLRSCR      Borrar la ventana actual (con un carcter opcional):

	       CLRSCR [ <Caracter> ]

	       Se usa el color actual para el borrado. Opcionalmente,
	       puede especificar un carcter para llenar la ventana.
	       Puede definirlo como un carcter encerrado en comillas
	       '"' o bien por su correspondiente valor numrico.


   CTEXT       Escribir texto centrado en la lnea actual:

	       CTEXT <P1> [, <P2>..]

	       <P1>, <P2>.. son variables o cadenas de carcteres.


   GOTOXY      Establecer posicin del cursor en la ventana actual:

	       GOTOXY <X>, <Y>

	       <X>, <Y> - La nueva posicin del cursor.


   DEFBAR      Define la barra de progreso de ficheros:

	       DEFBAR <Col>, <Bck>, <BarCol1>, <BarCol2>, <X>, <Y>, <Largo>

	       <Col>,
	       <Bck>     - color de texto y fondo;
	       <BarCol1>,
	       <BarCol2> - colores para las partes 'vacias'
			   y 'llenas' de la barra;
	       <X>, <Y>  - posicin de la esquina superior izquierda
			   de la ventana de la barra;
	       <Largo>   - longitud de la barra.

	       Puede desactivar la barra de progreso con una forma
	       especial de la orden DEFBAR:

	       DEFBAR OFF


   MESSAGE     Escribir texto en una caja:

	       MESSAGE <Col>, <Bck>, <Titulo>, <Str1> [, <Str2>..]

	       <Col>, <Bck> - colores de texto y fondo;
	       <Titulo>     - Ttulo de la caja;
	       <Str1>,
	       <Str2>..     - cadenas de texto a visualizar


   OUTTEXT     Inicio/final de un texto ASCII/ANSI:

	       OUTTEXT [ANSI] ON | OFF

	       Define el principio (ON) y el final (OFF) de una seccin
	       de texto. El parmetro opcional ANSI indica que el texto
	       contiene secuncias de escape ANSI que deben ser procesadas
	       al sacarse por pantalla.

	       Ejemplo:

	       OUTTEXT ON

		  Instrucciones de instalacin.

		  Debe instalar este programa siguiendo
		  el procedimiento siguiente:
		    ...


	       OUTTEXT OFF


   RESTSCR     Recuperar una pantalla grabada con SAVESCR:

	       RESTSCR <NumPan>

	       <NumPan> es el identificador de la pantalla previamente
	       guardada con la orden SAVESCR. Tambin se restauran la
	       posicin del cursor, la ventana definida y los colores
	       de fondo y texto.


   SAVESCR     Salvar pantalla:

	       SAVESCR <NumPan>

	       <NumPan> es un valor numrico entre 1 y 16 que identifica
	       el lugar donde se almacena la informacin de pantalla.
	       Los datos que se guardan incluyen el aspecto de la pantalla,
	       la posicin del cursor, los valores definidos para la
	       ventana actual y los colores de texto y fondo. Las
	       pantallas almacenadas con este mtodo pueden ser resta-
	       blecidas con la orden RESTSCR.


   SETCOLOR    Establece los colores de texto y fondo por defecto:

	       SETCOLOR <Col>, <Bck>

	       <Col> es el color del texto y <Bck> es el color de fondo.
	       Despues de procesar esta orden todas las dems ordenes
	       de salida a pantalla en las que no se especifiquen otros
	       colores usaran estos por defecto.


   TEXT        Escribir texto:

	       TEXT <P1> [, <P2>..]

	       <P1>, <P2>.. son variables o cadenas de carcteres que
	       contienen el texto a mostrar.


   WINDOW      Establecer la ventana actual:

	       WINDOW <X1>, <Y1>, <X2>, <Y2>

	       <X1>, <Y1> - la esquina superior izquierda de la ventana;
	       <X2>, <Y2> - la esquina inferior derecha de la ventana

	       Toda salida a pantalla procesada despues de esta orden
	       se colocar en la ventana especificada.


   2.1.3. Funciones

   Las funciones son procedimientos internos que devuelven un valor.


   EXEC        Ejecutar un comando del sistema operativo y devolver
	       el cdigo de retorno:

	       <Var>=EXEC <Arg1> [, Arg2.. ]

	       <Arg1>,
	       <Arg2>.. - componen la lnea de comandos a
			  ejecutar.
	       <Var>    - la variable donde se almacenar
			  el codigo de retorno (errorlevel).


   GETDFREE    Obtener el espacio disponible en disco:

	       <Var>=GETDFREE [<NumDis>]

	       <Var>    - variable donde almacenar el valor devuelto.
			  El espacio disponible, en bytes, es almacenado
			  en la variable.

	       <NumDis> - El nmero opcional del disco del que se quiere
			  conocer el espacio disponible (0 para A:, 1 - B:,
			  2 - C:, etc ..). Si se omite este parmetro se
			  devolver el espacio disponible del disco destino
			  (vea la descripcin de la varibale DestDisk).
			  Si el disco no existe devuelve -1.


   GETKEY      Devuelve el cdigo de la tecla pulsada:

	       <Var>=GETKEY

	       Esta funcin espera hasta que se haya soltado la tecla
	       y devuelve su cdigo en <Var>. Las teclas especiales
	       producen cdigos de rastreo extendidos en los cuales el
	       primer byte es cero y el siguiente contiene el cdigo
	       extendido. En este caso el cdigo de la tecla pulsada
	       es devuelto con un valor igual al segundo byte ms 256.


   INPUT       Entrada de datos:

	       <Res>=INPUT <Col>, <Bck>, <Var>, <ValorIni>, <MaxLong>

	       <Col>, <Bck> - el color de texto y fondo del campo de
			      entrada;
	       <Var>        - la variable donde almacenar el valor
			      entrado;
	       <ValorIni>   - el valor inicial (variable o constante);
	       <MaxLong>    - la longitud mxima de la entrada;
	       <Res>        - indicador lgico del estado de entrada.

	       Si se pulsa la tecla <Esc> durante la entrada de datos
	       se devuleve el valor cero en <Res> y <Var> se halla sin
	       definir. En caso contrario se devulve 1 en <Res> y se
	       asigna a <Var> la entrada producida.


   MENU        Inicia un men:

	       <Var>=MENU <X>, <Y>, <Col>, <Bck>, <Posicion>, <Titulo>,
			  <Item1> [, <Item2>..]

	       <X>, <Y>     - la esquina superior izquierda del men;
	       <Col>, <Bck> - el color de texto y fondo;
	       <Posicion>   - posicin inicial del puntero del men
			      (valor numrico);
	       <Titulo>     - ttulo del men;
	       <Item1>,
	       <Item2>..    - cadenas de carcteres - opciones del
			      men;
	       <Var>        - vaiable donde almacenar el valor devuelto.

	       Una vez seleccionada una opcin, la funcin devuelve el
	       nmero correspondiente (1-n). Si se pulsa <Esc>, devuelve
	       cero.


   2.1.4. Procedimientos predefinidos

   Son procedimientos con nombres reservados que son llamados desde el
   cdigo interno del mdulo SFX en determinadas condiciones. Antes de
   estas llamdas, el mdulo SFX establece los dos parmetros, Par1 y
   Par2. Los procedimientos predefinidos son opcionales y deben ser
   implementados segn la necesidad del programador usando la sentencia
   PROC.

   ArcDone     Llamado despes la extraccin correcta.

	       No se pasa ningn parmetro. Cando se ejecuta
	       ArcDone, el archivo es cerrado y puede ser
	       borrado usando la orden SYSTEM "Del ", ArcName

   ChangeVol   Llamado cada vez que se requiera un cambio de volumen.

	       Se asigna a Par1 el nmero del volumen (0 para el primer
	       cambio de volumen) y a Par2 el estado del volumen: si
	       Par2 es cero, se requiere el cambio de volumen (se ha de
	       pedir al usuario que lo cambie). Este procedimiento ser
	       llamado con Par2=0 hasta que no se encuentre el volumen
	       requerido. Puede cambiar el nombre del volumen requerido
	       asignandolo a la varibale ArcName. En este caso, si Par2
	       es diferente de cero, el volumen esta correctamente
	       instalado y no se requiere ninguna accin por parte del
	       usuario.

	       Si el procedimiento ChangeVol no esta definido, el mdulo
	       SFX preguntar "Inserte el disco con <nombre del volumen>"
	       cada vez que se requiera un cambio de volumen.

   Error       Llamado cuando ocurre algn error.

	       Se asigna a Par1 el cdigo de error:

		  1 - Error fatal
		  2 - Error en el CRC, archivo daado
		  3 - Error de escritura
		  4 - Error al crear fichero
		  5 - Error de lectura
		  6 - Error al cerrar fichero
		  7 - Error al abrir fichero
		  8 - Memoria insuficiente

	       Al finalizar la llamada a Error tambin finaliza la
	       ejecucin del mdulo SFX. Este procedimiento no es
	       llamado cuando se detecta un cdigo AV incorreto.

	       Si este procedimiento no est definido, el mdulo SFX
	       muestra el mensaje estandard de error y finaliza su
	       ejecucin.

   FileDone    Llamado despues de cada extraccin correcta de un
	       fichero o directorio.

	       Se asigna a Par1 el nmero de fichero del archivo.
	       Filename contiene el nombre del fichero.

   OnKey       Llamado cada vez que se pulsa una tecla.

	       Puede usarse para implementar ayudas sensibles al
	       contexto asi como para interrumpir el proceso en
	       curso. Se asigna a Par1 el cdigo de la tecla pulsada.
	       Si se procesa la tecla pulsada dentro de este procedi-
	       miento, deber asignar a Par1 el valor -1 para impedir
	       un procesamiento doble de la tecla por el mdulo SFX.
	       El mdulo SFX se encarga el mismo de evitar llamadas
	       recursivas a OnKey. Cada vez que se produce una llamada
	       a este procedimiento, la ventana actual, los colores
	       y la posicin del cursor son salvados y recuperados
	       automticamente al finalizar la llamada. Fijese en que
	       no se guarda el contenido de la pantalla, use las ordenes
	       SAVESCR y RESTSCR si lo desea, pero asegurese de usar un
	       identificador que no sea usado en el resto del script.


   2.1.5. Variables predefinidas


   Variables de archivo:

   ArcName       El nombre del archivo

   AVPresent     Si existe validacin de autenticidad (AV) tiene el
		 valor 1, 0 si no existe o -1 si existe pero no es
		 vlida.

   AVArcName     El nombre de archivo vlido, guardado en la AV.

   AVDate        La fecha vlida del archivo, guardada en la AV.

   AVUserName    El creador del archivo (cadena AV de registro).


   Variables dependientes de la extraccin:


   FileName      El nombre del fichero extrado del archivo (sin
		 la trayectoria de destino).

   DestFileName  La trayectoria completa del fichero extrado del
		 archivo.

   Variables definibles por el usuario (pueden definirse con INPUT
   o con la operacin '=') :

   DestDir       Directorio destino donde instalar los ficheros del
		 archivo. Si el directorio destino no existe ser
		 creado. Si el ltimo carcter no es una '\' o un ':'
		 entonces se le aadir de forma automtica la '\'
		 final.

   Password      La contrasea necesaria para desencriptar el archivo.


   2.1.6. Notas sobre los script

   Se pueden usar cadenas de carcteres al estilo del lenguaje C. Por
   ejemplo, use "\\" para el smbolo "\". Tambien puede usar carcteres
   especiales (formateadores) como "\n" o "\r".

   El texto del script se almacena como un comentario en el archivo SFX.
   Para evitar que el mdulo SFX visualize el texto del script debe
   aadir el carcter <EOF> (cdigo ASCII 26) al principio del script.

   Vea el ejemplo de script de instalacin en el ficher standard.s que
   puede usar para crear cualquier paquete de instalacin.

   Tambien puede extraer el script de instalacin del paquete SFX del RAR.
   Para esto debe utilizar la opcin "extraer comentario" en el archivo
   SFX:

       rar cw rar1_55.exe rarinst.s

   As tendr el script de instalacin de RAR en el fichero rarinst.s

   Puede incluir un programa externo de instalacin en el paquete SFX
   para ser llamado despues de la extraccin (por ejemplo, en PROC
   ArcDone) usando la funcin EXEC:

     PROC ArcDone

	  EXEC DestDir, "Install.Exe"
     ENDP

   2.1.7. Limitaciones tcnicas:

	Mxima longitud de lnea ...................... 1023 bytes

	Mxima longitud de script .....................   62 Kb

	Nmero mximo de parmetros en una orden .....    16

	Longitud mxima de los parmetros ............   255 bytes

	Longitud mxima de identificador
	(nombre de variable, etiquetas) ..............    31 bytes

	Longitud mxima de valor de variable .........   127 bytes

   En general, las variables pueden contener valores numricos (de
   hasta 4 bytes) o cadenas de hasta 127 carcteres.



