O exemplo a seguir define o layout da estrutura da linguagem C a seguir em z/OS:
typedef struct { char char_val; unsigned short ushort_val; short short_val; unsigned long ulong_val; long long_val; char string_val[32]; } _test;
Criando o layout do arquivo XML
O formato de arquivo XML está definido no arquivo DTD (definição do tipo de documento) layout.dtd da seguinte forma:
<?xml version="1.0" encoding="ISO-8859-1"?> <!ELEMENT LAYOUT (FIELD)+> <!ATTLIST LAYOUT Header CDATA #REQUIRED length CDATA #REQUIRED> <!ELEMENT GROUP EMPTY> <!ATTLIST GROUP Name CDATA #REQUIRED> <!ELEMENT FIELD (FIELD)*> <!ATTLIST FIELD Header CDATA #REQUIRED Type (16_BIT_INT|16_BIT_UINT|16_BIT_HINT|32_BIT_INT|32_BIT_UINT|32_BIT_HINT|32_BIT_FLOAT|64_BIT_INT|64_BIT_FLOAT|CHARACTER|HEX|ASCII|EBCDIC|STRUCTURE|PADDING|BIT|BITMASK|MAP) #REQUIRED length CDATA #REQUIRED layout CDATA #IMPLIED filename CDATA #IMPLIED Groups CDATA #IMPLIED>
Isso significa que o arquivo de layout XML primeiro especifica um cabeçalho (título) e o comprimento total do layout, seguido por uma lista de subelementos (FIELD) descrita por um cabeçalho (nome), comprimento e tipo primitivo que é utilizado para determinar a representação padrão desse subelemento.
Também há tipos especiais de subelementos:
O arquivo XML que descreve uma visualização em árvore da estrutura the_test e que está de acordo com este formato é:
<?xml version="1.0"?> <!DOCTYPE LAYOUT SYSTEM "Layout.dtd" > <LAYOUT Header = "A Layout" length="17"> <FIELD Header="char_val" Type="CHARACTER" length="1"></FIELD> <FIELD Header="ushort_val" Type="16_BIT_UINT" length="2"></FIELD> <FIELD Header="short_val" Type="16_BIT_INT" length="2"></FIELD> <FIELD Header="ulong_val" Type="32_BIT_UINT" length="4"></FIELD> <FIELD Header="long_val" Type="32_BIT_INT" length="4"></FIELD> <FIELD Header="string_val" Type="ASCII" length="32"></FIELD> </LAYOUT>
Definindo Campos de Preenchimento
Se decidir ignorar o campo long_val mas desejar mostrar o tipo string_val no layout, o arquivo XML se parecerá com:
<FIELD Header="short_val" Type="16_BIT_INT" length="2"></FIELD> <FIELD Header="ulong_val" Type="32_BIT_UINT" length="4"></FIELD> <FIELD Header="" Type="PADDING" length="4"></FIELD> <FIELD Header="string_val" Type="ASCII" length="32"></FIELD>
A finalidade inicial para definição dos subelementos PADDING é lidar com estruturas alinhadas de bytes, mas também pode ser utilizada para ignorar uma área de dados que não precisa ser detalhada no layout.
Definindo Estruturas
A peça de XML a seguir mostra o uso dos campos STRUCTURE para estruturas aninhadas de mapeamentos. Um elemento do alto da estrutura não possui um valor associado e pode ser expandido para mostrar seus subelementos. Enquanto o comprimento do campo STRUCTURE é adicionado ao tamanho total do layout XML, os tamanhos de campos incluídos possuem apenas finalidade de exibição. Por exemplo, a estrutura a seguir significa apenas 344 bytes fora do tamanho total do layout.
<FIELD Header="MACHINE CHECK LOG OUT AREA" Type="STRUCTURE" length="344"> <FIELD Header="reserved" Type="HEX" length="16"></FIELD> <FIELD Header="FLCSID" Type="HEX" length="4"></FIELD> <FIELD Header="FLCIOFP" Type="HEX" length="4"></FIELD> <FIELD Header="reserved" Type="HEX" length="20"></FIELD> <FIELD Header="FLCESAR" Type="HEX" length="4"></FIELD> <FIELD Header="FLCCTSA" Type="HEX" length="8"></FIELD> <FIELD Header="FLCCCSA" Type="HEX" length="8"></FIELD> <FIELD Header="FLCMCIC" Type="HEX" length="8"></FIELD> <FIELD Header="reserved" Type="HEX" length="8"></FIELD> <FIELD Header="FLCFSA" Type="HEX" length="4"></FIELD> <FIELD Header="reserved" Type="HEX" length="4"></FIELD> <FIELD Header="FLCFLA" Type="HEX" length="16"></FIELD> <FIELD Header="FLCRV110" Type="HEX" length="16"></FIELD> <FIELD Header="FLCARSAV" Type="STRUCTURE"length="64"> <FIELD Header="AR0" Type="HEX" length="4"></FIELD> <FIELD Header="AR1" Type="HEX" length="4"></FIELD> <FIELD Header="AR2" Type="HEX" length="4"></FIELD> <FIELD Header="AR3" Type="HEX" length="4"></FIELD> <FIELD Header="AR4" Type="HEX" length="4"></FIELD> <FIELD Header="AR5" Type="HEX" length="4"></FIELD> <FIELD Header="AR6" Type="HEX" length="4"></FIELD> <FIELD Header="AR7" Type="HEX" length="4"></FIELD> <FIELD Header="AR8" Type="HEX" length="4"></FIELD> <FIELD Header="AR9" Type="HEX" length="4"></FIELD> <FIELD Header="AR10" Type="HEX" length="4"></FIELD> <FIELD Header="AR11" Type="HEX" length="4"></FIELD> <FIELD Header="AR12" Type="HEX" length="4"></FIELD> <FIELD Header="AR13" Type="HEX" length="4"></FIELD> <FIELD Header="AR14" Type="HEX" length="4"></FIELD> <FIELD Header="AR15" Type="HEX" length="4"></FIELD> </FIELD> <FIELD Header="FLCFPSAV" Type="HEX" length="32"></FIELD> <FIELD Header="" Type="PADDING" length="64"></FIELD> <FIELD Header="" Type="PADDING" length="64"></FIELD> </FIELD>
As estruturas podem ser definidas internamente ou externamente para um layout. Uma estrutura externa pode ser criada como um layout aninhado especificando filename="<nome do arquivo>" no campo da estrutura, em que o arquivo referenciado por <nome do arquivo> contém a definição real da estrutura.
Por exemplo, a estrutura MACHINE CHECK LOG OUT AREA pode ser especificada em um layout de mapeamento externamente da seguinte maneira: <FIELD Header="MACHINE CHECK LOG OUT AREA" Type="STRUCTURE" length="344" filename="machine.xml"></FIELD>.
Definindo Campos de Máscaras de Bits
A parte de XML a seguir é uma amostra para descrição dos campos BITMASK. O comprimento de BITMASK é especificado em bytes e contém um conjunto de campos BIT para os quais o comprimento é especificado em bits. O deslocamento mostrado para os campos BIT é um deslocamento de bits dentro do campo BITMASK. Enquanto o comprimento do campo de máscara de bits é incluído no tamanho total do layout XML, os tamanhos individuais do campo BIT possuem apenas finalidade de exibição.
<FIELD Header="byte_field" Type="BITMASK"length="2"> <FIELD Header="hi_byte" Type="BIT" length="8"></FIELD> <FIELD Header="lo_byte" Type="BIT" length="8"></FIELD> </FIELD>
Definindo Layouts Aninhados
Com o tipo de campo MAP e campo de layout opcional juntos, é possível descrever layouts aninhados como no seguinte exemplo de layout DSA do z/OS:
<?xml version="1.0"?> <!DOCTYPE LAYOUT SYSTEM "Layout.dtd" > <LAYOUT Header = "DSA" length="72"> <FIELD Header="FLAGS" Type="HEX" length="2"></FIELD> <FIELD Header="junk" Type="HEX" length="2"></FIELD> <FIELD Header="Back Chain" Type="MAP" length="4" layout="dsa.xml"></FIELD> <FIELD Header="Forward Chain" Type="MAP" length="4" layout="dsa.xml"></FIELD> <FIELD Header="R14" Type="HEX" length="4"></FIELD> <FIELD Header="R15" Type="HEX" length="4"></FIELD> <FIELD Header="R0" Type="HEX" length="4"></FIELD> <FIELD Header="R1" Type="HEX" length="4"></FIELD> <FIELD Header="R2" Type="HEX" length="4"></FIELD> <FIELD Header="R3" Type="HEX" length="4"></FIELD> <FIELD Header="R4" Type="HEX" length="4"></FIELD> <FIELD Header="R5" Type="HEX" length="4"></FIELD> <FIELD Header="R6" Type="HEX" length="4"></FIELD> <FIELD Header="R7" Type="HEX" length="4"></FIELD> <FIELD Header="R8" Type="HEX" length="4"></FIELD> <FIELD Header="R9" Type="HEX" length="4"></FIELD> <FIELD Header="R10" Type="HEX" length="4"></FIELD> <FIELD Header="R11" Type="HEX" length="4"></FIELD> <FIELD Header="R12" Type="HEX" length="4"></FIELD> </LAYOUT>
Esse layout XML bem formulado é armazenado em um arquivo chamado DSA.XML. Desde que você saiba que os campos 3 e 4 contêm ponteiros para estruturas DSA diferentes, é possível adicionar duas definições de layout aninhado.
Definindo grupos
Com a sintaxe de grupo, é possível organizar em grupos os campos em layouts de mapeamento para que seja mais fácil trabalhar com eles. Para definir um grupo, é necessário colocar <GROUP Name="groupName"></GROUP> no início do arquivo de layout. Em seguida, indique se o campo pertence ao grupo predefinido especificando: <FIELD Header="RESERVED" Type="HEX" length="12" Groups="groupName"></FIELD>.
Um campo pode pertencer a vários grupos. Para definir vários grupos, especifique-os em uma lista delimitada por vírgulas no atributo Groups.
O nome de grupo ALL é um grupo especial. Sua especificação em um campo fará com que ele pertença a todos os grupos e o campo será visível em todos os grupos. A amostra de código a seguir contém grupos:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE LAYOUT SYSTEM "Layout.dtd" > <LAYOUT Header="GROUP_EXAMPLE" length="32"> <GROUP Name="GroupA"></GROUP> <GROUP Name="GroupB"></GROUP> <FIELD Header="FIELD_A" Type="HEX" length="8" Groups="GroupA"></FIELD> <FIELD Header="FIELD_B" Type="HEX" length="8" Groups="GroupB"></FIELD> <FIELD Header="FIELD_AB" Type="HEX" length="8" Groups="GroupA,GroupB"></FIELD> <FIELD Header="FIELD_ALL" Type="HEX" length="8" Groups="ALL"></FIELD> </LAYOUT>