Utilizando Variáveis de Substituição no Toolkit de Armazenamento

Esta seção explica como utilizar variáveis de substituição com o Toolkit de Armazenamento e fornece exemplos.

Você pode utilizar variáveis de substituição para indicar partes de um comando ou tarefa em lote do Toolkit de Armazenamento que necessitam de substituição por nomes de volumes, nomes de conjuntos de dados ou outros valores. O Limitações e Sugestões do Toolkit de Armazenamento fornece informações úteis sobre a utilização de variáveis de substituição.

Configurando Variáveis de Substituição para Comandos do Kit de Ferramentas

Muitos dos pedidos de ações que o Toolkit de Armazenamento gera podem incluir variáveis de substituição. Você pode definir essas variáveis na guia Comando na Etapa 6 como parte do seguinte procedimento geral sugerido:

Nota: Uma guia Comando não está presente na caixa de diálogo Criar Tarefa em Lote. Nessa caixa de diálogo, você configura as variáveis de substituição na guia Opções.

Clique com o botão direito do mouse nas linhas em uma das visualizações de um espaço de trabalho para acessar o menu pop-up.
Selecione o comando do Toolkit de Armazenamento que deseja chamar. A guia Opções é selecionada por padrão na caixa de diálogo.
Nota: Uma guia Opções não é fornecida na caixa de diálogo Emitir Comando, pois você utiliza esta caixa de diálogo para criar cadeias de comandos e parâmetros de formato livre. Se você estiver utilizando esta caixa de diálogo, siga para a Etapa 6
Faça seleções e insira valores na guia Opções, conforme apropriado.
Selecione a guia Comando. O campo Comando mostra como as opções que você selecionou na guia Opções são tratadas no texto bruto dentro de um comando.
Antes de realizar qualquer alteração na guia Comando, inspecione os parâmetros e a sintaxe do comando que são exibidos para garantir que eles correspondem com sua expectativa. Se necessário, modifique o comando utilizando uma das seguintes abordagens:
- Antes de realizar qualquer alteração na guia Comando, retorne para a guia Opções e modifique suas seleções.
  Nota: Se você realizar alterações na guia Comando, a guia Opções será desativada e você não poderá modificar as seleções realizadas nela. Para que possa trabalhar novamente com a guia Opções, você pode abrir uma nova instância da caixa de diálogo do kit de ferramentas. Clique em Cancelar para fechar a instância atual da caixa de diálogo e acesse novamente a caixa de diálogo por meio do Tivoli Enterprise Portal.
- Se você estiver familiarizado com a sintaxe do comando, edite o texto bruto que você vê no campo Comando da guia Comando. Tenha em mente que após realizar as alterações na guia Comando, você não poderá realizar modificações adicionais na guia Opções.
Se você deseja definir variáveis de substituição, acesse a guia Comando e as defina na área Variáveis de substituição e seus valores de substituição de tempo de execução. Em muitos casos, a tabela de variáveis de substituição e seus valores de substituição de tempo de execução são preparadas com variáveis e valores definidos pelo Toolkit de Armazenamento com base na ação e recursos que você selecionou.
Nota: Uma guia Comando não está presente na caixa de diálogo Criar Tarefa em Lote. Nessa caixa de diálogo, você configura as variáveis de substituição na guia Opções.
Clique no botão Mostrar Dados para acessar Caixa de Diálogo de Visualização de Dados para confirmar se os volumes ou conjuntos de dados corretos estão definidos como destino para as variáveis de substituição.

Variáveis de Substituição Padrão no Kit de Ferramenta

As seguintes diretrizes gerais se aplicam às variáveis de substituição que o kit de ferramentas utiliza:

O OMEGAMON for Storage on z/OS utiliza um par de sinais de porcentagem (%) cercando o nome SUBnn para identificar as variáveis de substituição que ele fornece, como por exemplo, %SUB01%.
Ao criar variáveis para os arquivos JCL, é recomendado que você utilize a convenção do sinal de porcentagem (%), como neste exemplo: %MY_VAR%. Esta convenção permite que o Toolkit de Armazenamento localize essas variáveis e liste-as automaticamente em Caixa de Diálogo Criar Tarefa do Lote. As variáveis que não seguem esta convenção não são listadas automaticamente na caixa de diálogo.
Não crie uma variável que possa ser um subconjunto de alguma outra variável. Por exemplo, não nomeie uma variável como MY_VARNAME e uma outra variável como MY_VAR.
Não crie uma variável que possa corresponder com dados em seu comando, arquivos JCL ou código JCL gerado que não deve ser substituído. Por exemplo, no cenário a seguir um valor pode ser substituído mas que não deveria ser substituído:
1. Você define uma variável ADDR e a designa um valor de 01AE.
2. Você utiliza a variável no seguinte comando:
```
ANALYZE UNITADDRESS(ADDR) SCAN
```
3. A substituição automática da variável ADDR geraria o comando a seguir. O comando gerado inclui uma modificação no parâmetro UNITADDRESS que pode ter efeitos indesejados:
```
ANALYZE UNIT01AEESS(01AE) SCAN
```
DISP é um outro exemplo de um nome de variável que não é recomendado porque essa cadeia provavelmente apareceria em uma instrução DD JCL, em que ela não deve ser substituída.
O produto fornece nomes de atributos genéricos, tais como *DSN e *ROWNUMBER.

Para visualizar o escopo das variáveis de substituição que você define na guia Opções, clique no botão Mostrar Dados.

Como os comandos são executados quando variáveis de substituição são definidas

Você especifica variáveis de substituição e seus mapeamentos na área Variáveis de substituição e seus valores de substituição de tempo de execução da caixa de diálogo. Dependendo de suas configurações, o pedido de ação emite o comando uma ou mais vezes da seguinte maneira:

Número de linhas selecionadas no espaço de trabalho	As variáveis de substituição são definidas na guia Comando?	Como o comando é executado
Um	Sim ou não	Uma vez para o item selecionado.
Várias	Sim	Várias vezes; uma vez para cada item selecionado.
Um ou mais grupos	Sim. O atributo de grupo é especificado.	Uma vez para cada volume ou recurso do conjunto de dados em cada grupo selecionado.

Exemplos de Variáveis de Substituição

A tabela de exemplo a seguir mostra as variáveis de substituição típicas para um comando que é emitido pelo Toolkit de Armazenamento. Uma tabela similar de duas colunas é fornecida nas caixas de diálogo do kit de ferramentas.

Variável de Comando¹	Atributo ou Cadeia²
`%dsname%`	`ENTRYNAME`
`my-volser`	`VOLUME`
`%job-name%`	`"USER01A"`
`%sysout-class%`	`"X"`
`%rownum%`	`*ROWNUMBER`
`%user-account%`	`*USERID`

O título desta coluna é "Variável" quando estiver definindo variáveis de substituição para uma tarefa em lote na caixa de diálogo Criar Tarefa em Lote. Consulte Sobre a Coluna "Variável de Comando" (ou "Variável") para obter informações adicionais.
Você pode inserir um texto bruto ou utilizar um menu drop-down para selecionar as entradas na coluna de atributos ou cadeias. Consulte Sobre a coluna "Atributo ou Cadeia" para obter informações adicionais.

Sobre a Coluna "Variável de Comando" (ou "Variável")

Um exemplo da coluna Variável de Comando (ou Variável) para variáveis de substituição é mostrado em Exemplos de Variáveis de Substituição. Esses exemplos refletem nomes de variáveis de substituição que podem estar presentes no código JCL definido pelo usuário. Os exemplos ilustram as seguintes diretrizes e características para as entradas na coluna Variável de Comando:

As cadeias podem consistir em até 64 caracteres a partir da seguinte coleção de caracteres: [a-zA-Z0-9_.%-]. As cadeias não fazem distinção entre maiúsculas e minúsculas quando processadas pelo agente de mainframe.
O caractere de e comercial (&) não é suportado para uma variável de substituição. Caso contrário, poderá haver confusão com outra utilização do e comercial dentro do código JCL.
Não permita que os nomes de variáveis sejam uma subcadeia de uma outra variável de substituição. Por exemplo, não utilize my_dsn e my_dsname como variáveis de substituição.
Não crie uma variável que possa corresponder com dados em seu comando, arquivos JCL ou código JCL gerado que não deve ser substituído. Por exemplo, DISP não é recomendado como nome de uma variável de substituição, pois essa cadeia provavelmente aparecerá em uma instrução DD JCL, em que ela não deve ser substituída.

Sobre a coluna "Atributo ou Cadeia"

Um exemplo da coluna Atributo ou Cadeia para variáveis de substituição é mostrado em Exemplos de Variáveis de Substituição. Na maioria dos casos, os valores para as variáveis de substituição são tirados de colunas de dados no espaço de trabalho em que o pedido de ação do kit de ferramentas é originado. Você utiliza a lista drop-down na coluna Atributo ou Cadeia para selecionar um valor. Este valor é utilizado como a origem de valores para a variável de substituição correspondente.

O kit de ferramentas detecta as entradas disponíveis para a linha que você seleciona em um espaço de trabalho antes da chamada de uma caixa de diálogo do Toolkit de Armazenamento. A Exemplos de Variáveis de Substituição ilustra as seguintes diretrizes e características para as entradas na coluna Atributo ou Cadeia:

ENTRYNAME: Neste exemplo, o usuário selecionou um atributo de tabela, ENTRYNAME, em uma caixa de listagem, para o valor da variável.
USER01A: Neste exemplo, o usuário digitou um nome literal (USER01A) para correspondência com a variável %job-name%.
%job-name%, %sysout-class%: Você pode inserir cadeias de texto literal nesta coluna em vez de nomes de atributos. O texto bruto pode fazer referência a itens no código JCL que não estão relacionados à tabela subjacente, tais como %job-name%, %sysout-class% e assim por diante. O kit de ferramentas trata um valor que você coloca entre aspas simples ou duplas inserido como uma cadeia literal em vez do nome de uma coluna de tabela. Uma única ocorrência desta cadeia é utilizada na tarefa em lote ou comando.
*ROWNUMBER: Neste exemplo, o usuário selecionou o valor *ROWNUMBER no menu drop-down que corresponde à variável %rownum%. Como resultado desta configuração, um número variável de linhas é gerado para utilização no código JCL. O kit de ferramenta gera números inteiros de 1 ao número total de linhas de dados sendo transmitidas a partir da tabela subjacente. Por exemplo, você pode selecionar três linhas a partir de uma visualização de espaço de trabalho ao criar ou enviar novamente um pedido de ação. Neste caso, os valores 1, 2 e 3 seriam gerados.
*USERID: Neste exemplo, o usuário selecionou o valor *USERID no menu drop-down que corresponde à variável %user-account%. Esse valor é preenchido com uma única ocorrência do nome da conta de usuário que está atualmente ativa no Tivoli Enterprise Portal.
Os pontos a seguir se aplicam à configuração de tarefas em lote no diálogo Criar Tarefa em Lote:
- Quando o kit de ferramentas tem como objetivo um membro de um conjunto de dados particionado ou um conjunto de dados sequencial que já existe, o kit de ferramentas varre esse arquivo em busca de cadeias que atendem a seguinte convenção de nomenclatura: %name%, em que name é o nome de uma variável de substituição. O kit de ferramentas preenche a caixa de diálogo com cada uma das variáveis correspondentes para %name%.
- A substituição dos valores para variáveis dentro do código JCL pode gerar linhas mais longas que 72 caracteres. Se isso ocorrer, a execução desse pedido de ação falhará. Um status de JCL Inválido é exibido no espaço de trabalho Resumo de Resultados.
- A substituição de valores para variáveis dentro de outros conjuntos de dados que requerem substituição de variável pode produzir linhas maiores do que 80 caracteres. Se isso ocorrer, a execução desse pedido de ação falhará. Um status do InvalidJCL é exibido na área de trabalho Resumo de Resultados.
- Quando a configuração da tarefa em lote é concluída, você clica em OK na caixa de diálogo Criar Tabela em Lote. Nesse ponto, o arquivo JCL que você fornece e quaisquer arquivos fora da JCL que contêm variáveis de substituição são copiados em arquivos temporários. Estes arquivos temporários são usados quando a JCL da tarefa em lote é submetida. O kit de ferramentas não modifica os arquivos originais, porque outros usuários podem estar fazendo referência aos arquivos ao mesmo tempo.