# Tutorial Breve

Indice principal

Este tutorial asume que el usuario tiene conocimientos básicos sobre Hojas de Cálculo, el sistema operativo FreeDos y el compilador FreePascal.

## Nuestra primera Hoja de Cálculo

Para iniciar este tutorial, vamos a suponer que usted se encuentra utilizando el sistema operativo FreeDos en este subdirectorio o alguno de funcionalidad similar, con el programa CAFE2011.EXE instalado.

      C:\FDOS\CAFE\CAFE2011\BIN>

Vamos ahora a ingresar al modo normal de CAFE. Para ello digite CAFE2011 -n en dicho subdirectorio.

Si usted se equivoca en algún momento de esta primera etapa; puede digitar el comando Salida de CAFE, y volver a comenzar de nuevo.

      C:\FDOS\CAFE\CAFE2011\BIN>CAFE2011 -n

Ya ingresamos, no debería aparecer ningún mensaje. A continuación digite uno a uno todos los siguientes renglones, apretando ENTER cada vez. Cada vez que ingrese un renglón el sistema CAFE emitirá una serie de mensajes, que ocuparán como mínimo cinco renglones.

      CrearHojaTrabajo(10,10,'FACIL')
      A1:='FACIL'
      A2:='X'
      B2:=24.5
      A3:='f(X)'
      B3(X):=Sqr(X)-2*X
      A4:='f(24.5)'
      B4():=B3(B2)
      GuardarHoja('FACIL.TXT','GRUPO001')
      A1:B4
      Salida

Ya salimos del sistema CAFE. Busque algún editor de texto, y examine al archivo de texto 'FACIL.TXT'; debería notar que es muy similar al código anterior.

Volvamor ahora a CAFE; pero en esta ocasión lo vamos a utilizar de Calculadora. Para ellos ingresamos desde el sistema operativo FreeDOS CAFE2011 -r.

      C:\FDOS\CAFE\CAFE2011\BIN>CAFE2011 -r

Hemos ingresado a un modo, que probablemente sea más fácil de utilizar en programas pequeños. Nos encontramos en la Hoja de Cálculo $Temporal, que sirve para transferencia en el copiado de casillas entre Hojas diferentes.

      (Sumatoria(XI,XI,0,5))
      Salida

Debería haber obtenido un número 15 como respuesta en la pantalla. El modo breve, entiende todas las órdenes, pero es menos informativo.

Volvamos a entrar al modo normal.

      C:\FDOS\CAFE\CAFE2011\BIN>CAFE2011 -n

Podemos abrir el archivo anterior para consulta interior de CAFE ingresando las siguientes instrucciones.

      AbrirHoja('FACIL.TXT')
      Recalculo
      Salida

Vamos a cometer un error intencional, en una nueva ejecución de CAFE.

      A1:=10
      A2():=1/(A1-10)
      RecalculoConErrores(A1:A2)
      Salida

El sistema CAFE permite trabajar con varias hojas, organizadas en grupos. Las hojas que pertenezcan a un mismo grupo, pueden accesar a sus variables, y se guardar como un conjunto.

      C:\FDOS\CAFE\CAFE2011\BIN>CAFE2011 -n

Vamos a crear un grupo de dos hojas intercomunicadas.

      NuevoGrupoGuardar
      CrearHojaTrabajo(20,20,'Hoja1')
      CrearHojaTrabajo(20,20,'Macros')
      ActualManejador
      ActualGrupoGuardar

Las últimas dos instrucciones, nos informan de la Hoja de Cálculo activa, y del grupo al que pertenece. El número de control, permite diferenciar entre hojas del mismo nombre en grupos diferentes. Los nombres, sin embargo; no puden repetirse en un mismo grupo.

      A1(X):=5*X-3
      // CAFE ignora comentarios
      A1
      A2(X):=4*X*X+8
      A2
      ActivarHojaTrabajo('Hoja1')
      A1:=(Macros.A1(7))
      (* Esta asignación asigna el valor *)
      A2():=Macros.A1(7)
      (* Esta asigna una expresión *)
      (A1+A2)
      GuardarHoja('PAR.TXT','GRUPO001')
      Salida

Si examina el archivo 'PAR.TXT', notará como indican los comentarios que A1 es un valor real y A2 una expresión en 'Hoja1'.

CAFE intenta imitar los comentarios como FreePascal, aunque con algunas diferencias importantes. Por ejemplo, CAFE no entiende comentarios antes del := de una asignación, y sólo permite comentarios de un renglón. Puede ingresar renglones en blanco.

## Asignaciones

A imitación del FreePascal se utiliza := para las asignaciones. Podemos asignar valores booleanos, enteros, reales fechas y String. Podemos ingresar el valor equivalente a una expresión colocando la misma entre paréntesis.

      A1:=TRUE
      A2:=FALSE
      A3:=89
      A4:=10/12/2011
      A5:='Hola me llamo CAFE'
      A6:=Null
      A7:=(1/3)
      A8:=(A2 OR A1)

También podemos ingresar expresiones funcionales, con un paréntesis después del nombre de la casilla.

      A1():=Sum(B1:B3)
      A4():=A3 OR True
      A5():=Copiar('HOLA:JORGE',6,5)+' es mi nombre'

Podemos ingresar macros funcionales, que aceptan valores reales; y retornan valores reales, ingresando identificadores FreePascal entre paréntesis.

      A7(X):=1/(1-X)
      A8(X,Y,Z):=X+Y+Z
      A9(Ga,Ge):=5*Ga-10/Ge

La sintaxis puede complicarse un poco más. Debe tomar en cuenta que los ciclos recursivos se encuentran impedidos con variables generales del ambiente de la Hoja de Cálculo por defecto.

Asignación de expresiones | Parámetros (generalmente pueden modificarse posteriormente, aunque será complicado evitar un mensaje de error, pero se puede lograr).
A1() A1(Hex1) A1(Hex1,Ent1) A1(X) A1(X,Y) A1(X,Y,Z) A1(X,Real1) A1(X,Real1,Y,Real2) A1(X,Real1,Y) A1(X,Y,Real2) A1(X,Real1,Y,Real2,Z,Real3) A1(X,Real1,Y,Real2,Z) A1(X,Real1,Y,Z,Real3) A1(X,Real1,Y,Real2,Z) A1(X,Real1,Y,Z) A1(X,Y,Real2,Z) A1(X,Y,Z,Real3) A1(Hex1,X) A1(Hex1,X,Y) A1(Hex1,X,Y,Z) A1(Hex1,X,Real1) A1(Hex1,X,Real1,Y,Real2) A1(Hex1,X,Real1,Y) A1(Hex1,X,Y,Real2) A1(Hex1,X,Real1,Y,Real2,Z,Real3) A1(Hex1,X,Real1,Y,Real2,Z) A1(Hex1,X,Real1,Y,Z,Real3) A1(Hex1,X,Real1,Y,Real2,Z) A1(Hex1,X,Real1,Y,Z) A1(Hex1,X,Y,Real2,Z) A1(Hex1,X,Y,Z,Real3) A1(Hex1,Ent1,X) A1(Hex1,Ent1,X,Y) A1(Hex1,Ent1,X,Y,Z) A1(Hex1,Ent1,X,Real1) A1(Hex1,Ent1,X,Real1,Y,Real2) A1(Hex1,Ent1,X,Real1,Y) A1(Hex1,Ent1,X,Y,Real2) A1(Hex1,Ent1,X,Real1,Y,Real2,Z,Real3) A1(Hex1,Ent1,X,Real1,Y,Real2,Z) A1(Hex1,Ent1,X,Real1,Y,Z,Real3) A1(Hex1,Ent1,X,Real1,Y,Real2,Z) A1(Hex1,Ent1,X,Real1,Y,Z) A1(Hex1,Ent1,X,Y,Real2,Z) A1(Hex1,Ent1,X,Y,Z,Real3) | Hex1 : Valor hexadecimal $3 por defecto. Corresponde a una clave de descripción de casilla. El número se calcula por suma de los siguientes términos. Algunas combinaciones recomendadas son $3, $33 y $5B. $0001 obligatorio $0002 obligatorio en esta versión $0004 Ciclo Recursivo por evaluación $0008 Finalizar ciclo recursivo con error $0010 Obligatorio en ciclos $0020 En caso de ciclo se toma valor $0040 Ciclo Recursivo $0080 Casilla con iniciativa, no propaga en el recálculo Ent1 : Número entero máximo de ciclos recursivos permitidos en la casilla. Valor 10 por defecto. X : Un identificador válido; comienza en letra, si existe se define una macro real de variable real. Si ausente se entiende que es una expresión corriente. Real1 : Valor de prueba para X. Valor 0 por defecto. CAFE exige que la macro funcione en el valor de prueba. Y : Un identificador válido; comienza en letra. Real2 : Valor de prueba para Y. Valor 0 por defecto. CAFE exige que la macro funcione en el valor de prueba. Z : Un identificador válido; comienza en letra. Real3 : Valor de prueba para Z. Valor 0 por defecto. CAFE exige que la macro funcione en el valor de prueba.

## Grupos e intérpretes

A toda Hoja de Cálculo le corresponde un intérprete exclusivo, pero no todo intérprete tiene una Hoja de Cálculo asociada. Sin embargo; en esta versión de CAFE no es posible crear intérpretes sin Hojas de Cálculo, pero se prevee su existencia en el futuro próximo.

El programa CAFE siempre tiene un intérprete definido por defecto $Temporal. Es el intérprete que se activa al iniciar el programa, y al inicio de todo proceso AbrirHoja(). Su función principal es servir de intermediario en copias de casillas entre Hojas de Cálculo diferentes. A su propio riesgo, el usuario puede utilizar $Temporal como calculadora o sus propios fines. Pero CAFE tiene autorización, y cualquier hoja lo tiene; de modificar su contenido sin permiso. Para utilizar $Temporal en procesos de copia, puede consultar en el glosario Hacia$Temporal() y Desde$Temporal.

Los intérpretes se organizan en grupos. Sus características principales serían (no estrictas):

1. El intérprete $Temporal pertenece al grupo del mismo nombre.
2. Un grupo de intérpretes puede guardarse en disco con una sola instrucción GuardarHoja().
3. Los intérpretes de un mismo grupo, pueden accesar mediante subregistro muchas de sus variables y procesos.
4. Intérpretes de diferentes grupos, no se pueden accesar mediante subregistro simple.
5. Todos los intérpretes dentro de un mismo grupo tienen nombres diferentes. Se permite que diferentes grupos tengan intérpretes con el mismo nombre.
6. Todos los grupos activos de CAFE deben tener nombres diferentes, y los intérpretes deben tener claves secuenciales distintas. Generalmente estos datos serán asignados por CAFE, y tendrán existencia transitoria modificándose libremente en cada ejecución.

A modo de ejemplo, uniremos dos Hojas de Cálculo en un solo grupo.

      AbrirHoja('..\EJEMPLOS\EJEMPLO1.TXT')
      Recalculo
      AbrirHoja('..\EJEMPLOS\EJEMPLO2.TXT')
      // Tiene varias integrales y raíces, paciencia...
      Recalculo
      ListaGruposGuardar
      ListaManejadores('GRUPO001')
      ListaManejadores('GRUPO002')
      ActivarHojaTrabajo('PHHOCL.TXT')
      AgregarHoja('FTMINIMO','GRUPO001')
      ListaGruposGuardar
      ListaManejadores('GRUPO001')
      ListaManejadores('GRUPO002')
      DestruirGrupoGuardar('GRUPO002')
      GuardarHoja('DOBLE.TXT','GRUPO001')
      Salida

Si examinamos 'DOBLE.TXT' notará que contiene dos Hojas de Cálculo. Por lo general, cuando se activa un intérprete se activa su grupo respectivo. La activación de un grupo implica, que será el destino preferentes para las siguientes hojas que se agreguen. Los procesos AbrirHoja() generan uno o más grupos diferentes de los actuales, y CAFE trata de impedir el acceso a los grupos ya existentes, excepto $Temporal. Los archivos generados por CAFE mediante GuardarHoja() generarían a lo sumo un grupo como máximo, al menos en esta versión. Una excepción a esta regla, es cuando se aplica GuardarHoja('Rapido.TXT','$Temporal'), que no genera ningún nuevo grupo.

## Mensajes largos

CAFE utiliza la asignación de Input, Output y StdErr Standard realizada por el compilador FreePascal.

El sistema de mensajes de CAFE se creó previendo la existencia de cierto procesamiento paralelo. En la actualidad y por defecto, CAFE procesa todas sus instrucciones en el modo interno "WaitOnCompleted", esto significa que procesa una a una cada instrucción hasta terminarla. En este estado por defecto, se considera que el mecanismo de mensajes, resulta innecesariamente complicado. Pensando en ello se creo el modo Breve que se activa ingresando CAFE2011 -r del que hablaremos adelante.

La estructura base de todo mensaje largo es:

      Name=Value

El formato de Name se da a continuación. Cada símbolo porcentaje representa un número del 0 al 9, y la palabra Tipo se sustituye por la palabra apropiada. El total de símbolos de porcentaje es seis por defecto, se prevee poder modificar el número en el futuro.

      %%%%%%TipoREPO%%%%%%

La primera secuencia de digitos varía desde uno hasta 900000, y luego reinicia en uno. La orden cero corresponde al sistema CAFE y requiere algún tipo de autorización del usuario. Las restantes después de 900000 están reservadas para procesamiento paralelo, prohibido por defecto.

La segunda secuencia de números, indica el número de veces que se ha repetido el mismo tipo de mensaje, para la misma orden. Su objetivo es identificar sin confusión respuestas secuenciales.

Los diferentes TipoREPO, pueden consultarse en el glosario. Internamente CAFE tiene definido una lista mayor de tipos, todavía sin uso. El uso del sufijo REPO es obligatorio.

La mayoría de las veces el valor de Value es simplemente una secuencia de seis ceros. Esto corresponde a un estilo numeral de Value, para mensajes no enlistados. En esta versión se reconocen dos estilos de Value; el estilo numeral y el estilo casilla. El estilo numeral tiene el siguiente formato:

      #0%%%%%% 'String1' 'String2' 'String3'

El elemento importante es 'String1'. Podría sin embargo estar ausente al igual que los demás string. Cuando el numeral es diferente de cero; debería corresponder en alguna lista con 'String1' más una o varias sustituciones internas entrecomilladas. 'String2' tiene como finalidad la rotulación, y 'String3' la sustitución del mensaje por un archivo. Sin embargo, 'String3' no se utiliza del todo en CAFE y 'String2' en raras ocasiones.

Se prevee que surjan otros estilos de mensajes. La idea es que el elemento relevante sea 'String1', y el elemento anterior cumpla funciones de identificación. Es decir, que un programa que utilice CAFE lo utilice para generar su propio sistema de mensajes de usuario, sin necesidad de entender el español...

El estilio casilla corresponde al siguiente formato:

      #C(Entero1,Entero2,Entero3,Entero4) 'String1' 'String2' 'String3'

El valor de Entero1 corresponde a alguna columna de la Hoja de Cálculo numerada a partir de uno. Entero2 corresponde a la fila. Entero3 identifica la naturaleza general del mensaje. Entero4 se refiere a alguna lista numerada de mensajes.

Actualmente Entero3 únicamente pude tomar los valores 1, 2 o 3. Que corresponden respectivamente a errores de sintaxis, ejecución y copia.

Cuando se trabaja con el modo "WaitOnCompleted" único en esta versión. Es probable que el usuario prefiera el modo Breve; que será más fácil de interpretar por un programa director, aunque menos informativo. Las reglas de este modo Breve, serían las siguientes:

1. Los mensajes NombreREPO, ResultREPO y DatoREPO (unimplemented) se informan como 'String1' únicamente, luego de aplicar una eliminación primaria de comillas. Por tanto los elementos de sustitución permanezcerán entrecomillados.
2. Los mensajes ExitoREPO, FracasoREPO y FatalREPO se informan como EXITO, FRACASO y FATAL sin comillas.
3. Los demás mensajes se ignoran. Se prevee que la existencia de procesos más complejos, presione la modificación de esta última regla ante la aparición de nuevos tipos de mensajes. Disculpas, por las molestias que esto pueda causar. Por ejemplos mensajes como WaitREPO, ArchivoREPO, PeticionREPO, SolicitudREPO, NumeroIDRepo, LlaveREPO, HaltREPO etc... todavía no implementados por CAFE. Sin embargo, se prevee un trámite similar a las reglas uno y dos.

El modo Breve actúa asumiendo que el programa director casi no comete errores. Así que probablemente, el usuario se sienta un poco pérdido de si CAFE le está haciendo caso o ignorando.

### ¿Transferencias de binarios?

CAFE prohíbe la transferencia de binarios por defecto. En la actualidad no se encuentran implementadas este tipo de transferencias, pero se prevee que surjan en el futuro cercano. El plan es utilizar una combinación de WaitREPO en Input Standard y LibreWaitREPO en StdErr Standard. No me agrada mucho la idea, por otra violación de las reglas del StdErr, pero me preocupa el tiempo de preparación después del WaitREPO que podría surgir casi inmediatamente ante una solicitud del usuario. El binario se transferiría por medio del Output Standard, y el StdErr informaría de la completitud de la transferencia. Para facilitar su captura por parte del usuario su numeración sería con la orden cero así: 000000WAITREPO...=.... Todo esto se encontraría prohibido por defecto, y en tal caso se desviaría la información a algún archivo en disco.

## ¿Ahora qué hago...?

Es nuestro deseo, crear una versión mejor y más larga de este tutorial. Por el momento, lo invitamos a leer algunos términos que le interesen de nuestro Glosario.

### Sobre LibreN3D

En la actualidad programo casi dos horas todos los días para desarrollar el programa de animación LibreN3D con el compilador FreePascal para FreeDOS. El objetivo es crear mallas tridimensionales en movimiento y con simulaciones físicas, que puedan combinarse con el programa POV-Ray para generar animaciones tridimensionales. Confío en unos diez años poder lograr animaciones completas de aceptable calidad. En la actualidad, intento agregarle características elásticas a los objetos. He tenido numerosos retrasos, así que todavía no funciona. Lo siento...(29/febrero/2012), pero me siento muy seguro de que pronto lo lograré. De momento, no tiene interface con el usuario, pero se encuentra en desarrollo como intérprete de renglón al estilo DOS. LibreN3D no es compatible con POR-Ray, pero resulta relativamente simple coordinar el esfuerzo de ambos programas.

Me sería de muchísima ayuda, que el grupo FreePascal completará para Go32v2 las unidades Process, Pipes y Timer entre otras; pues de esa manera establecería una relativamente fácil comunicación entre LibreN3D y CAFE. Los siguientes son enlaces que podrían ser de utilidad para el interesado en los proyectos POV-Ray, FreePascal y FreeDOS.

Descarga sistema operativo FreeDOS

Descarga compilador FreePascal

Programa de animación por rastreo de rayos POV-Ray