Experimental: Configure las aplicaciones con archivos ZAPP

Esta versión temprana de ZAPP tiene como objetivo ofrecer una primera impresión de algunas de las ideas y recopilar comentarios. Los archivos ZAPP se pueden utilizar actualmente para especificar las configuraciones siguientes:

• Grupos de propiedades para buscar archivos de inclusión local o remoto proporciona una alternativa completa a los valores descritos en la sección Establecimiento de grupos de propiedades.

• Grupos de propiedades para definir opciones de compilador específicas del lenguaje que afectan al modo en que los servidores de lenguajes IBM® interpretan el código fuente.

• Correlaciones de páginas de códigos para la API RSE definiendo correlaciones para patrones de nombre de archivo sobre cómo se deben cargar y descargar de MVS, lo cual está completamente documentado en la sección Archivos de correlaciones y páginas de códigos EBCDIC de MVS.

• Compilación de usuario para crear sus programas actualmente editados en Z Open Editor de forma remota con la oferta de IBM Dependency Based Build. (Puede encontrar la documentación detallada de esta característica en IBM Knowledge Center).

Cree un archivo ZAPP en el espacio de trabajo de desarrollo, es decir, el directorio de nivel superior que normalmente contiene el directorio .git si utiliza git, y/o el directorio de nivel superior que se abrirá en VS Code con Archivo > Abrir.... Normalmente este directorio contiene también el directorio .vscode en el que se pueden almacenar los valores del espacio de trabajo, que anteriormente también era la ubicación donde se alojaban los grupos de propiedades y los valores de compilación de usuario, que ahora se pueden almacenar en los archivos ZAPP.

Nota: Esta versión actual de ZAPP solo da soporte a los espacios de trabajo de VS Code de raíz única y a los espacios de trabajo de Eclipse Che/Red Hat CodeReady.

Puede elegir editar el archivo ZAPP como un archivo YAML o como un archivo JSON y crear un archivo con cualquiera de los nombres siguientes en el directorio de nivel superior. El archivo debe el mismo nombre para permitir que los editores YAML o JSON reconozcan el esquema que se va a utilizar.

• zapp.yaml

• zapp.json

Si decide utilizar YAML, que es el formato recomendado, se recomienda que instale Red Hat YAML VS Code Extension. Esta extensión de VS Code proporciona características de finalización de código, documentación y formato, que son útiles para ZAPP. Z Open Editor puede reconocer la instalación de la extensión YAML de Red Hat automáticamente y configurar el esquema ZAPP para esta extensión en los valores de usuario del VS Code. Además, se da soporte a fragmentos de código para ZAPP en YAML, aportando productividad inmediata.

Si utiliza JSON, el editor JSON de VS Code predeterminado también proporciona la terminación y el formato de código, pero actualmente no hay fragmentos de código.

Para verificar que Z Open Editor se ha configurado para trabajar con la extensión Red Hat YAML o VS Code JSON, busque entradas como se muestra a continuación en los valores de usuario de VS Code. Las entradas se deben añadir después de iniciar Z Open Editor.

"yaml.schemas": {
  "file:///Users/user1/.vscode/extensions/ibm.zopeneditor-1.1.0/resources/zapp-schema-0.0.1.json": [
    "zapp.yaml"
  ]
},
"json.schemas": [
  {
    "fileMatch": [
      "/zapp.json"
    ],
    "url": "file:///Users/user1/.vscode/extensions/ibm.zopeneditor-1.1.0/resources/zapp-schema-0.0.1.json"
  }
]

Ahora se puede crear el primer archivo ZAPP.

Nota:: Debido a que se trata de una nueva característica experimental, las formas anteriores de especificar el contenido de un archivo ZAPP en los valores de usuario y espacio de trabajo siguen siendo válidas y se pueden seguir utilizando todos los valores que ha creado con versiones anteriores de Z Open Editor. No obstante, no puede combinar y correlacionar valores en diferentes ubicaciones.

Z Open Editor busca grupos de propiedades y valores de compilación de usuario en el orden siguiente y utiliza sólo el primer conjunto que encuentra:

1. zapp.yaml en el directorio del espacio de trabajo.

2. zapp.json en el directorio del espacio de trabajo.

3. .vscore/settings.json en el directorio del espacio de trabajo, que es el valor del espacio de trabajo de VS Code que se especifica en el menú Preferencias.

4. Los valores de usuario que especifique en el menú Preferencias, que se almacenan en una ubicación diferente específica del usuario en función del sistema operativo.

Puede empezar con ZAPP clonando nuestro repositorio de GitHub de ejemplo en

https://github.com/IBM/zopeneditor-sample.

Este repositorio contiene los siguientes archivos de configuración para que pueda probar todas las variantes y decidir qué le conviene:

• Un archivo zapp.yaml

• Un archivo zapp.json

• Valores del espacio de trabajo de herencia

Nota:: Según las reglas de prioridad indicadas en la sección anterior, si desea probar el archivo zapp.json, primero debe suprimir o cambiar el nombre del archivo zapp.yaml.

El archivo zapp.yaml contiene los siguiente:

name: sam
description: Wazi's code samples with COBOL, PL/I, and HLASM applications
version: 1.1.0
author:
  name: IBM CORPORATION

property-groups:
  - name: cobol-local
    language: cobol
    type: local
    syslib:
      - "**/COPYBOOK"
    libraries:
      - name: MYFILE
        locations:
          - "**/COPYLIB"
  - name: pl1-local
    language: pl1
    compilerOptions: not(!)
    type: local
    syslib:
      - "**/INCLUDES"
  - name: hlasm-local
    language: hlasm
    type: local
    syslib:
      - "**/ASMCOPY"
  - name: zowe-mvs
    type: mvs
    system: zos1000.example.com
    syslib:
      - USER1.SAMPLE.COBCOPY
    libraries:
      - name: MYLIB
        locations:
          - USER1.SAMPLE.COPY

Este sencillo ejemplo define cuatro grupos de propiedades. Los tres primeros son del tipo local y definen la ubicación para los archivos de inclusión para el proyecto zopeneditor-sample para cada lenguaje. Las propiedades que se definen para cada grupo de propiedades se escriben exactamente igual que como se indica para los valores de espacio de trabajo/usuario y se muestran en la página de referencia grupos de propiedades para comprobar que estén completas.

La diferencia es que estos grupos de propiedades ahora no se mezclan con los ajustes del editor y se pueden editar de forma mucho más eficiente en YAML.

La terminación de código requiere que tenga la extensión YAML de código de Red Hat VS instalada y configurada como se ha descrito anteriormente. Puede probarlo de este modo:

1. Coloque el cursor detrás de la línea con type: mvs (alrededor de la línea 34) y pulse Intro para iniciar una nueva línea.

2. Pulse Control+Espacio para abrir el desplegable de finalización de código.

A continuación, muestra dos propiedades que todavía podrían añadirse aquí: language y compilerOptions, que todavía no están especificadas por este grupo de propiedades de mvs remoto.

ZAPP también proporciona fragmentos de código para que pueda especificar rápidamente nuevos grupos de propiedades de este modo.

1. Coloque el cursor en la línea vacía al final del archivo.

2. Pulse Control+Espacio de nuevo y verá cuatro fragmentos de código listados en el menú desplegable.

3. Desplácese hacia abajo y seleccione Grupos de propiedades de MVS remoto de ZAPP pulsando la tecla Intro.

4. Puede ver que se inserta un nuevo grupo de propiedades con marcadores de posición resaltados.

5. Antes de pulsar o escribir cualquier otra cosa, mientras los marcadores siguen resaltados, utilice las teclas Tab y Mayús+Tab para navegar entre los marcadores de posición y entre los valores para el nombre, el idioma (utilizando otra lista desplegable) y las entradas de syslib.

6. Al final de los nuevos grupos de propiedades, añada otra entrada syslib añadiendo una nueva línea y especificando un nuevo valor como, por ejemplo, -USER1.SAMPLE.INCLUDES.

Recuerde que necesita proporcionar un archivo YAML válido. Puesto que la entrada syslib necesitaba una matriz de series en JSON, ahora debe especificarse en YAML como una lista ordenada utilizando - para cada valor.

También hay una plantilla de fragmento de código para un archivo ZAPP completo. Puede probarlo de este modo:

1. En la ventana del editor actual para zapp.yaml, seleccione todo y suprima todo el contenido del archivo. Puede deshacer la supresión más tarde, ya que el archivo se gestiona en Git.

2. En la primera línea y columna del documento vacío, pulse Control+Espacio y seleccione el fragmento de código ZAPP Template. En lugar de desplazarse a la parte inferior, puede escribir este nombre de fragmento.

3. Verá que se ha insertado un fragmento de código que contiene un grupo de propiedades local y remoto. A continuación, puede realizar las modificaciones que sean necesarias.

Además de utilizar Control+Espacio, también puede insertar fragmentos de código a través de la galería de fragmentos de VS Code accesible siguiendo los pasos siguientes:

1. Pulse Cmd+Mayús+ P (Mac) o Control+Mayús+P (Windows).

2. Seleccione Insertar fragmento de código en el menú desplegable. Puede escribir snippet para reducir la lista.

Cuando cree un archivo zapp.yaml no válido escribiendo nombres incorrectos de YAML o escribiendo nombres de propiedades incorrectos, la extensión YAML de Red Hat le mostrará errores de sintaxis en la vista Problemas. Puede probarlo de este modo:

1. Elimine algunas letras de cualquier propiedad para crear errores de sintaxis.

2. Cambie a la vista Problemas de VS Code. Utilice el menú Vista > Vista de problemas si no lo ve. Ahora esta vista muestra el error de sintaxis exacto, así como la línea y la columna en la que se ha generado.

Si no tiene instalada la extensión YAML de Red Hat, todavía puede encontrar listas de errores simples proporcionadas por Z Open Editor en la vista Salida como se indica a continuación:

1. Cambie a la vista Salida. Utilice el menú Vista > Vista de salida si no lo ve.

2. En la parte derecha de la vista Salida, seleccione IBM Z Open Editor en el menú desplegable.

3. Escriba con algún error de sintaxis. Tenga en cuenta que mientras que la extensión de Red Hat le mostrará errores de inmediato, aquí no verá ningún error hasta que intente guardar.

4. Guarde el archivo con el error de sintaxis. Ahora a vista de salida mostrará mensajes de error, como por ejemplo should NOT have additional properties(additionalProperty:lauage).

Como puede ver, la salida aquí es mucho más sencilla y no tiene números de línea. La extensión de Red Hat es, con mucho, la solución superior para editar archivos ZAPP ya que dicha extensión incluye un servidor de lenguaje YAML completo que genera una vista Esquema.

Otra función de la extensión de Red Hat YAML es la capacidad de dar formato a su archivo ZAPP de forma coherente. Si ha utilizado sangrías diferentes en las ubicaciones, simplemente puede corregir el formato de todo el archivo utilizando uno de los dos métodos de formato siguientes:

• Utilice el acceso directo Mayús+Opción+F (Mac) o Mayús+Alt+F (Windows).

• Pulse Cmd+Mayús+P (Mac) o Control+Mayús+P (Windows) y escriba "format" para seleccionar Formatear documento.

Si ha utilizado grupos de propiedades con versiones anteriores de Z Open Editor y desea convertirlos a ZAPP, puede hacerlo con uno o dos sencillos pasos.

1. Copie los grupos de propiedades en un archivo zapp.json.

2. (Opcional) Convertir zapp.json en zapp.yaml.

Estos son los pasos detallados:

1. Cree un archivo zapp.json vacío con un objeto vacío { }.

2. Utilice la terminación de código en el archivo JSON para especificar algunas propiedades necesarias y opcionales como, por ejemplo, el nombre, la versión y el autor.

3. Abra el espacio de trabajo de VS Code o el archivo de valores de usuario en el que había almacenado anteriormente los grupos de propiedades.

4. Corte toda la entrada de grupos de propiedades del archivo de valores y péguela dentro del objeto de zapp.json. El resultado debe ser similar al objeto JSON siguiente:

   {
     "name": "sam",
     "zopeneditor.propertygroups": [
       {
         "name": "SAM-Copybooks",
         "type": "local",
         "syslib": ["**/COPYBOOK", "**/INCLUDES", "**/ASMCOPY"]
       }
     ]
   }

5. Cambie "zopeneditor.propertygroups" por "property-groups".

6. Formatee el archivo pulsando Mayús+Opción+F (Mac) o Mayús+Alt+F (Windows).

7. Realice una prueba para ver si se resuelven los archivos de inclusión.

El archivo resultante es similar al siguiente:

{
  "name": "sam",
  "property-groups": [
    {
      "name": "SAM-Copybooks",
      "type": "local",
      "syslib": ["**/COPYBOOK", "**/INCLUDES", "**/ASMCOPY"]
    }
  ]
}

Puede convertir fácilmente un archivo zapp.json válido en un archivo zapp.yaml utilizando otra extensión de VS Code de terceros como se indica a continuación.

1. Instale una extensión de VS Code que pueda realizar dicha conversión; por ejemplo, YAML+JSON.

2. Con esta extensión, ahora puede pulsar con el botón derecho del ratón en los archivos zapp.json y seleccionar Convertir a YAML.

3. Cambie el nombre del archivo resultante, zapp.yml, por zapp.yaml.

4. Realice una prueba para ver si los grupos de propiedades se resuelven correctamente.