programmer s guide - csi international, inc

Programmer’s Guide

Version 2 Release 2

TCP/IP is a communications facility that permits bi-directional communication

between VSE-based software and software running on other platforms

equipped with TCP/IP. This manual describes the application programming interfaces available with

TCP/IP FOR VSE.

Published October 2017 Copyright © by CSI International

Copyright © 1996–2017 by CSI International

All Rights Reserved

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the Government is subject to the restrictions as

set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer

Software clause at DFARS 252.227-7013.

This material contains confidential and proprietary material of Connectivity

Systems, Inc., hereafter referred to as CSI International and CSI, and may not be

used in any way without written authorization from CSI International. This

material may not be reproduced, in whole or in part, in any way, without prior

written permission from CSI International.

Permission is hereby granted to copy and distribute this document as follows:

• Each copy must be a complete and accurate copy.

• All copyright notices must be retained.

• No modifications may be made.

• The use of each copy is restricted to the evaluation and/or promotion of

CSI International’s TCP/IP FOR VSE product or in accordance with a

license agreement.

TCP/IP FOR VSE Programmer’s Guide

Version 2 Release 2

October 2017

Published by CSI International

Phone: 800-795-4914

Fax: 740-986-6022

Internet: http://www.csi-international.com

Product questions: [email protected]

Technical support: [email protected]

Review comments: [email protected]

CSI International Technical Support

During Business Hours Monday through Friday, 9:00 A.M. through 5:00 P.M. EST/EDT. Telephone: Toll Free in the USA 800-795-4914 Worldwide 740-420-5400

Email: [email protected] Web: http://csi-international.com/problemreport_vse.htm

Emergency Service 24/7 After business hours and 24 hours on Saturday and Sunday: Telephone: Toll Free in the USA 800-795-4914

Worldwide 740-420-5400

CSI International provides support to address each issue according to its severity.

Updates to This Manual

La siguiente tabla describe las actualizaciones de este manual. Las

actualizaciones pueden ser identificadas por un número de arreglo en la base de

datos de soporte de CSI International.

Octubre 2017

ID Cambiar Descripción Page

Capítulo 6, SSL / TLS para las API de VSE, "API de capa de sockets seguros":

• Para cada función, se agregó una referencia al Apéndice C: TLS 1.2 Mejora. 125

• Se agregó una nota sobre TLS 1.2 a “Opciones de asistencia de hardware 125 Configuración ".

• gsk_initialize (): se agregó el protocolo TLS 1.2 a sec_types. 132

• gsk_secure_soc_init (): se agregó el protocolo TLS 1.2 a sec_type 138

Apéndice A: Fase de opciones de $ SOCKOPT:

• Opciones actualizadas para TLS 1.2. 196

• Sección agregada: "Nueva configuración de $ SOCKOPT para TLS 1.2". 201

Apéndice C: Mejora de TLS 1.2:

Se agregó el Apéndice C para cubrir el soporte de TLS 1.2. 208

ii

Tabla de Contenidos

To return from a hyperlink jump, press <Alt> <◄>

Soporte Técnico Internacional CSI............................................................................................... i

Actualizaciones a este Manual...................................................................................................... ii

1. SOCKET Assembler API............................................................................................................. 1

SOCKET Macro ........................................................................................................................... 1

Syntax .................................................................................................................................. 1

Operando function ................................................................................................................... 2

Operando type ......................................................................................................................... 4

Keyword Parametros............................................................................................................. 5

Global Constant Area ........................................................................................................... 8

Connecting to TCP/IP FOR VSE............................................................................................ 8

Return Codes........................................................................................................................ 8

SRBLOK DSECT ..................................................................................................................10

Abrir una Conexión…….........................................................................................................12

Receiving Data.......................................................................................................................13

Status.....................................................................................................................................15

Cerrar una Conexion..............................................................................................................17

Control de Conecion......................................................................................................................18

Resolver nombres Simbólicos................................................................................................18

Sample Programs...........................................................................................................................22

2. BSD Socket Interface...................................................................................................................23

Visión General................................................................................................................................23

Lenguajes...............................................................................................................................23

Que es un Socket? ........................................................................................................................24

Definicion ...............................................................................................................................24

Socket vs. Port.......................................................................................................................24

Usando Socket Functions .............................................................................................................26

TCP Servidor .........................................................................................................................26

TCP Cliente ...........................................................................................................................26

Conectado a TCP/IP...............................................................................................................27

Descripciones de funciones...........................................................................................................28

iii

Table of Contents

abort( ) ...............................................................................................................................28 accept( )..............................................................................................................................28 bind( ) .................................................................................................................................29 close( ) ...............................................................................................................................30 connect( )............................................................................................................................31 getclientid( )........................................................................................................................31 gethostbyaddr( )..................................................................................................................32 gethostbyname( ) ...............................................................................................................32 gethostid( )..........................................................................................................................33 gethostname( )....................................................................................................................33 getpeername( )....................................................................................................................34 getsockname( ) ...................................................................................................................34 getsockopt( ) .......................................................................................................................35 getversion( ) ........................................................................................................................35 givesocket( )........................................................................................................................36 listen( ) ................................................................................................................................37 receive( ), recv( ) ................................................................................................................38 recvfrom( )...........................................................................................................................39 select( )................................................................................................................................40 selectecb( )..........................................................................................................................41 selectex( ) ...........................................................................................................................42 send( ) ................................................................................................................................43 sendto( ) .............................................................................................................................44 seterrs_default( ).................................................................................................................45 seterrs_socket( )..................................................................................................................45 setsockopt( )........................................................................................................................46 setsysid( )............................................................................................................................47 shutdown( ) .........................................................................................................................47 socket( )...............................................................................................................................48 takesocket( )........................................................................................................................49

Storage Functions ......................................................................................................................50 bcopy( ) ...............................................................................................................................50 bzero( ).................................................................................................................................50 htonl( ) .................................................................................................................................51 htons( ) ................................................................................................................................51 inet_addr( ) ..........................................................................................................................51 inet_lnaof( ) .........................................................................................................................52

C Definitions................................................................................................................................53 Definitions File......................................................................................................................53 Address Tag Struct..............................................................................................................53 IPv4 Address Struct.............................................................................................................53 Client ID Struct ....................................................................................................................53 Macros ................................................................................................................................54

iv

Table of Contents

Assembler Definitiones ...............................................................................................................56 Estructura de direcciones ...........................................................................................................56 Programas de muestra …............................................................................................................56 Manejo de errores .......................................................................................................................58 Códigos de retorno y números de error.....................................................................................58 Descripciones de nuero de erros ................................................................................................58 Ensamblador y programas de COBOL …...................................................................................59 Depuración de aplicaciones.........................................................................................................60 3. High Level Pre-Processor API…...........................................................................................61 Visión general .............................................................................................................................61 Ejecutando Legacy JCL...............................................................................................................61 Pre-compiler Procesamiento ......................................................................................................62 Compilando su programa…….....................................................................................................64 Usando el Pre-Processor...........................................................................................................65 Orden de ejecucion ....................................................................................................................65 Parámetros .................................................................................................................................65 Códigos de retorno Pre-Processor ............................................................................................67 Declaraciones Pre-Processor .....................................................................................................67 Identificando Tag.........................................................................................................................68 Verbos de comandos..................................................................................................................69 Terminación de linea .................................................................................................................79 Comprobación de errores ..........................................................................................................81 Blocke de control XOBLOK .......................................................................................................81 Determinación de error ..............................................................................................................83 Conexiones y trasmisiones de datos..........................................................................................84 Ejemplos de conexión activa .....................................................................................................84 Ejemplos de conexión pasiva.....................................................................................................85 Recibiendo información ............................................................................................................85 Enviando información ................................................................................................................87 Cerrando una conexión ...........................................................................................................88 Usando WAIT(NO) ...................................................................................................................88 Sample Programs.....................................................................................................................90 COBOL EXEC TCP Ejemplo ...................................................................................................90 COBOL EXEC FTP Ejemplo ...................................................................................................93 COBOL EXEC CLIENT LPR Ejemplo......................................................................................96 PL/1 EXEC TCP Ejemplo ........................................................................................................99 PL/1 Notas .............................................................................................................................100 4. REXX Sockets API............................................................................................................101 Visión general ........................................................................................................................101 REXX llamadas ......................................................................................................................102 Variables ................................................................................................................................102

Codigos de retorno......................................................................................................104

v

Table of Contents

Function de tiempo de espera.................................................................................................105 Tipos de Socket ......................................................................................................................106 Codificacion de llamadas REXX .............................................................................................108 ABRIR......................................................................................................................................108 CERRAR..................................................................................................................................109 ENVIAR....................................................................................................................................110 RECIBIR ..................................................................................................................................111 ABORTAR ...............................................................................................................................111 STADO.....................................................................................................................................112 Obteniendo informacion de la red............................................................................................113 Inicio de una conexion de control ............................................................................................113 Iniciar conexion de cliente........................................................................................................114 5. Common Gateway Interfaces ...........................................................................................115 Vision general ..........................................................................................................................115 Usando CGIs con VSE ............................................................................................................116 Definiendo un CGI to VSE........................................................................................................116 Usando el CGILOAD Utility ......................................................................................................116 Eliminando un CGI ...................................................................................................................117 ensamblador CGIs ...................................................................................................................118 Ejemplo ....................................................................................................................................118 REXX CGIs ..............................................................................................................................121 Programando............................................................................................................................121 Requisites de ejecucion ....................................................................................................... 122 Ejemplo ...................................................................................................................................122 6. SSL/TLS for VSE APIs ......................................................................................................124 Vision general .........................................................................................................................124 Copia de conexion segura (SSL) y Transport Layer Security (TLS) API ................................125 Configuraciones de opcion de asistencia a Hardware.............................................................125 Codigos de error.......................................................................................................................126 Funciones ................................................................................................................................126 gsk_free_memory( ) ................................................................................................................127 gsk_get_cipher_info( ).............................................................................................................128 gsk_get_dn_by_label( )...........................................................................................................130 gsk_initialize( ).........................................................................................................................131 gsk_secure_soc_close( ).........................................................................................................134 gsk_secure_soc_init( ) ............................................................................................................136 gsk_secure_soc_read( )..........................................................................................................142 gsk_secure_soc_reset( ) .........................................................................................................144 gsk_secure_soc_write( )...........................................................................................................145 gsk_uninitialize( ) .....................................................................................................................146 gsk_user_set( ) ........................................................................................................................147

vi

Table of Contents

CryptoVSE API.....................................................................................................................148 Vision general ......................................................................................................................148 cry_3des_cbc_encrypt( ) ................................................................................................... 149 cry_3des_cbc_decrypt( ) ................................................................................................... 150 cry_aes128_cbc_encrypt( )...................................................................................................151 cry_aes128_cbc_decrypt( )...................................................................................................152 cry_aes128_ecb_encrypt( )...................................................................................................153 cry_aes128_ecb_decrypt( )...................................................................................................154 cry_aes192_cbc_encrypt( )...................................................................................................155 cry_aes192_cbc_decrypt( )...................................................................................................156 cry_aes192_ecb_encrypt( )...................................................................................................157 cry_aes192_ecb_decrypt( )...................................................................................................158 cry_aes256_cbc_encrypt( )...................................................................................................159 cry_aes256_cbc_decrypt( )...................................................................................................160 cry_aes256_ecb_encrypt( )...................................................................................................161 cry_aes256_ecb_decrypt( )...................................................................................................162 cry_des_cbc_encrypt( ).........................................................................................................163 cry_des_cbc_decrypt( ).........................................................................................................164 cry_des_encrypt( ) ...............................................................................................................165 cry_des_decryt( ) .................................................................................................................166 cry_gen_random( )................................................................................................................167 cry_get_cert_info( )...............................................................................................................168 cry_hmac_md5( )..................................................................................................................169 cry_hmac_sha( ) ..................................................................................................................170 cry_initialize( ) ......................................................................................................................171 cry_md5_hash( )...................................................................................................................172 cry_rsa_encrypt( ) ................................................................................................................173 cry_rsa_decrypt( ) ................................................................................................................174 cry_rsa_genprvk( ) ...............................................................................................................175 cry_rsa_signature_create( ) .................................................................................................176 cry_rsa_signature_verify( ) ...................................................................................................177 cry_sha_hash( ) ...................................................................................................................178 cry_sha2_hash( )..................................................................................................................179 cry_universal_print_encode( ) .............................................................................................180 cry_universal_print_decode( ) .............................................................................................181 Common Encryption Cipher Interface ..................................................................................182 Calling the CIALCECI Stub...................................................................................................182 Request Area........................................................................................................................183 Return Codes........................................................................................................................185 Encryption Pseudocode........................................................................................................185 Encryption Flow ...................................................................................................................188 Decryption Pseudocode ......................................................................................................189

CIALSEED JCL .........................................................................................................190

Vii

Table of Contents

Cipher Suite Seleccion ......................................................................................................193 Problema de depuracion ...................................................................................................194 Notas de programa ............................................................................................................195 Appendix A: $SOCKOPT Options Phase........................................................................196 Usando $SOCKOPT...........................................................................................................196 Fase predeterminada .........................................................................................................196 Ejemplo 1: estableciendo el Stack ID .................................................................................197 Ejemplo 2: estableciendo el Default Cipher Suite...............................................................198 BSD opcion interfaz ............................................................................................................199 SSL/TLS opcion interfaz......................................................................................................201 Nuevo $SOCKOPT configurando para TLS 1.2..................................................................201 Appendix B: $SOCKDBG Debugging Phase...................................................................203 Usando $SOCKDBG ...........................................................................................................203 Trabajo de muestra...............................................................................................................203 Configuraciones de palabras claves.....................................................................................204 Ejemplo 1: BSD aplicación de salida....................................................................................206 Ejemplo 2: SSL/TLS aplicacion de entrada .........................................................................206 Controlando mensajes $SOCKDBG ...................................................................................207 Appendix C: TLS 1.2 Enhancement ................................................................................208 Vision general .....................................................................................................................208 Usando TLS 1.2 ..................................................................................................................208 Punto de entrada ................................................................................................................209 Soporte de versiones de protocolo anteriores.....................................................................209 Valor de Suite desifrado......................................................................................................210 Pseudo Random Facility (PRF)..........................................................................................211 Configuracion de MacroTLSVSE..................................................................................... 211

viii

1 1. SOCKET Assembler API

SOCKET Macro

La macro SOCKET es la interfaz de nivel más bajo para TCP / IP FOR VSE. Debido a

que es una interfaz Assembler, le da al programador Assembler Más flexibilidad

que cualquier otra interfaz de programación. Puedes usar el Macro SOCKET para

comunicarse con TCP, UDP, TELNET y FTP. La macro SOCKET también actúa como

una interfaz de cliente de uso general.

Sintaxis La sintaxis de la macro SOCKET sigue. Los valores predeterminados están

subrayados.

label SOCKET function,type,

ACTIVE=[YES|NO], CICS=[YES|NO], DATA=[(address,length)|NULL], DESC=descriptor,

ECB=resultarea,

ECB2=2ndecbaddr,

FAST=[YES|NO], FOIP=[0|foreignipaddr], FOPORT=[0|foreignportnum], ID=[00|nn], LOPORT=[0|localportnum], MF=[E|L], MFG=soparea,

NEGOT=[YES|NO], TIMED=[YES|NO], TIMEOUT=[36000|timevalue], USESYS=[YES|NO], WAIT=[YES|NO] La persona que llama debe cumplir los siguientes requisitos:

• AMODE debe ser 24 o 31.

• RMODE debe ser 24 o CUALQUIERA.

Además, la macro SOCKET emite SVC que deben ejecutarse en un estado

habilitado

1

Chapter 1 SOCKET Assembler API

Operando function El primer operando de la macro SOCKET es la función, que indica el función de la

macro. La siguiente tabla describe los valores válidos.

Valor function

Descripción

ABORT Cuando específica ABORT, todos los envíos y recibos pendientes son abortados y el zócalo está cerrado. Este es un cierre anormal y puede hacer que aparezca un mensaje de reinicio al otro lado del conexión.

CLOSE Cuando especifica CLOSE, la conexión especificada se cierra. La operación de cierre pretende ser elegante en el sentido de que Los SEND pendientes se transmiten hasta que se envían todos los datos. Está aceptable para emitir varias ENVIAR llamadas seguido de un CIERRE llamar y esperar que todos los datos se envíen al destino. El usuario Puede cerrar la conexión en cualquier momento. Porque cerrar una conexión requiere comunicación con el zócalo externo, las conexiones pueden permanecer en el estado de cierre durante un poco tiempo.

DSECT Cuando especifica DSECT, la macro SOCKET produce el SRBLOK DSECT. El SRBLOK DSECT asigna los 56 bytes área de resultado especificada por el operando BCE.

OPEN Cuando especifica ABRIR, también debe especificar si la conexión es PASIVA o ACTIVA. Si configura PASIVO = SÍ, está escuchando un mensaje entrante conexión. Una apertura pasiva puede tener una especificación completa zócalo externo (FOIP = nnn.nnn.nnn.nnn y FOPORT = nnnnn) esperando una conexión de cliente específica, o una no especificada socket externo (FOIP = 0 y FOPORT = 0) esperando a cualquier cliente conexión. Una aplicación de servidor normalmente comienza con un abierto pasivo en un número de puerto pre asignado y luego espera Conexiones de clientes. Para conectarse a la aplicación del servidor, un cliente debe conocer la dirección IP y el número de puerto del servidor. Si establece ACTIVE = YES, el procedimiento para establecer el La conexión comienza de inmediato. Una aplicación cliente normalmente comienza con una apertura activa y luego intenta conectarse a un aplicación de servidor específica que está escuchando pasivamente (esperando para conexiones de clientes). La dirección IP y el número de puerto del cliente se envían al servidor durante el procesamiento abierto activo, por lo tanto permitiendo que el servidor envíe datos al cliente.

2


Valor function

Descripción

RECEIVE Cuando especifica RECEIVE, se llena un búfer de recepción con todos los datos disponibles o tantos datos como puedan contener. Por ejemplo, si especifica 2000 bytes y solo llegan 100, entonces 100 bytes son recibidos El búfer restante está vacío. Además, si tú especifique 100 bytes pero se envían 2000 bytes, entonces 100 bytes son recibidos y los 1900 bytes restantes requieren adicional RECIBE. El SRECB del área de resultados se publica cuando el búfer receptor contiene datos y el campo SRCOUNT del El área de resultados contiene la longitud de los datos recibidos. No hay una estructura inherente en el flujo de datos. La aplicación debe emitir Múltiples RECEPCIONES hasta que la correcta Se recupera la cantidad de datos. Además, si espera y especifica un cantidad dada, la cantidad recibida aún puede ser menor si el envío de la pila divide los datos. Debes diseñar la aplicación programa para determinar dinámicamente cuando los datos entrantes Los segmentos están completos. Para hacer esto, puede incluir una longitud prefijo o use delimitadores únicos.

SEND Cuando especifica ENVIAR, los datos contenidos en el especificado Se envía el búfer de usuario. Se publica el SRECB del área de resultados. Cuando el búfer de datos es aceptado por el TCP / IP PARA VSE dividir.

SET_SYSID Cuando especifica SET_SYSID, habilita la macro para alterar la ID de pila TCP / IP FOR VSE predeterminada a la que la aplicación El programa se conecta. Si especifica USESYS = YES en OPEN solicitud y // OPTION SYSPARM = 'xx' contiene un valor de dos bytes, esa especificación anula el SET_SYSID mando. Para facilitar las pruebas de aplicaciones, le recomendamos que utilice // // OPTION SYSPARM = xx y USESYS = YES en lugar de el comando SET_SYSID para especificar TCP / IP PARA VSE apilar.

STATUS Cuando especifica ESTADO, recibe un bloque de datos que contiene la siguiente información: socket local, extranjero socket, nombre de conexión local, ventana de recepción, ventana de envío, estado de conexión, número de buffers en espera de confirmación, cantidad de memorias intermedias pendientes de recibo, estado urgente y tiempo de espera de transmisión. Según el estado de conexión o la implementación en sí, parte de esta información puede no ser disponible o significativo. El DSECT que asigna estos datos se llama STATBLK. Está mapeado por la macro STATBLK.

3


Operando type El segundo operando de la macro SOCKET es type, que indica el tipo de conexión

que está utilizando La siguiente tabla describe la validez valores.

Valor type Descripción

CLIENT Se conecta con el administrador de clientes de uso general. El cliente el administrador se ejecuta en la partición y controles TCP / IP FOR VSE las funciones de algunos protocolos independientes. Por ejemplo, un programa de aplicación que utiliza el gerente general del cliente puede manipular LPR.

CONTROL Se conecta a un administrador de control. El administrador de control permite un programa de aplicación para solicitar servicios del sistema del Partición TCP / IP PARA VSE. Por ejemplo, puede usar el interfaz de control para traducir un nombre de dominio a una dirección IP.

FTP Se conecta a FTP. El administrador del cliente FTP se ejecuta en el Partición TCP / IP FOR VSE y gestiona la sesión FTP. Después la solicitud abierta está completa, un programa de aplicación puede enviar Comandos FTP y recibir respuestas a esos comandos a través de la conexión. Esto permite que un programa de aplicación manipular una sesión de cliente FTP.

TCP Utiliza la interfaz TCP para conectarse y comunicarse. Esta le permite establecer una conexión TCP en el cliente o servidor modo para que pueda transferir un flujo de datos TCP hacia o desde un programa de aplicación.

TELNET Se conecta a un administrador de clientes TELNET. El cliente TELNET El administrador se ejecuta en la partición TCP / IP FOR VSE y gestiona el protocolo TELNET. Después de un TELNET abierto completa, los datos se envían y reciben como una transmisión TELNET. El programa de aplicación no necesita preocuparse por ASCII-to-Traducción EBCDIC o los detalles de la opción TELNET negociaciones.

UDP Le permite transmitir o recibir un datagrama UDP de un Puerto extranjero y dirección IP. Porque UDP no está basado en una conexión sistema, pasa datos en forma de bloques llamados UDP datagramas.

4


Parametros Keyword Los parámetros restantes en la macro SOCKET son operandos de palabras clave.

Estos se describen en la siguiente tabla:

Keyword Descripción

ACTIVE= [YES|NO]

Indica si TCP / IP FOR VSE debería intentar conectarse con un host extranjero o esperar a que un host extranjero conéctese con él (estado de escucha). En caso afirmativo, la conexión es establecida. Si especifica UDP como su valor de conexión, no Se establece la conexión real. El valor predeterminado es NO.

CICS=[YES|NO] Indica si la macro SOCKET debe generar código eso funciona en el entorno CICS. En caso afirmativo, se generan llamadas EXEC CICS apropiadas para reemplazar el Sistema operativo estándar GETVIS y WAIT llamadas. El valor predeterminado es NO.

DATA= [(address,length)|

NULL]

Identifica un bloque de datos a transmitir o un área para ser utilizado para una operación de recepción. Puedes especificar un simple 'cadena' para una transmisión. Cuando se refiere a un búfer de datos, debe especificar la dirección y la longitud como se muestra en el formato macro. Estos campos pueden referirse a una palabra completa que contiene la dirección o en un registro que contiene la dirección ((reg1), (reg2)). Si especifica el valor de la palabra clave NULL con una solicitud de recepción, recibe una señal de finalización sin ninguna transferencia de datos, y puedes programar recibe posteriormente para recuperar los datos. No hay defecto.

DESC=descriptor Identifica el hilo de la operación. Este campo debe apuntar a un palabra completa en almacenamiento en la que el valor del descriptor puede ser almacenado, y este descriptor debe pasarse a todos los subsiguientes SOCKET pide la conexión abierta. En otras palabras, después de establecer una conexión, cualquier número de Se pueden hacer llamadas SOCKET independientes a la conexión, pero todos deben usar el campo DESC para identificar la apertura conexión. El descriptor se establece mediante la llamada ABIERTA y es la dirección del área de trabajo del socket (SOWORK). Esta área es obtenida dinámicamente, utilizado para todos los SOCKET adicionales llamadas, y luego liberado por la llamada CERRAR. No hay defecto.

ECB=resultarea Apunta a un área de 14 palabras completas que contiene macro SOCKET resultados. Una vez que se completa una solicitud SOCKET, los resultados son almacenados en el área especificada. Esta área es inicializada por el Llamada SOCKET. No hay defecto.

5


Keyword Descripción ECB2=2ndecbaddr Apunta a un segundo BCE. Esta palabra completa del BCE se

publica en SOCKET macro finalización. Para controlar la espera en Operaciones SOCKET, una aplicación puede usar área de resultados del BCE original o esta segunda área del BCE. Ahí no está ningún valor predeterminado. A diferencia del parámetro BCE =, este BCE no se inicializa por la llamada SOCKET Esto significa que muchos concurrentes las operaciones pueden compartir el mismo valor ECB2 =, y cuando es publicado, la aplicación puede examinar el BCE individual = campos para determinar las operaciones completadas.

FAST=[YES|NO] Para FAST = NO (el valor predeterminado), el BCE de envío o cierre es publicado cuando el host remoto reconoce la solicitud. Si se especifica RÁPIDO = SÍ en CERRAR o ENVIAR funciones, el BCE se publica de inmediato y no hay esperando que el host remoto responda.

FOIP= [0|foreignipaddr]

Identifica la dirección IP externa que TCP / IP FOR VSE debe conectarse o transmitir a. Esta palabra clave debe usarse en Una llamada abierta activa. El valor predeterminado es 0. Si codifica un valor para una conexión PASIVA (ACTIVO = NO), entonces ese valor es Se utiliza como una máscara para limitar las conexiones entrantes a un determinado anfitrión.

FOPORT= [0|foreignportnum]

Identifica el número de puerto externo que TCP / IP FOR VSE es para conectarse o transmitir a. Esta palabra clave debe ser utilizada en una llamada abierta activa. El valor predeterminado es 0.

ID=[00|nn] Identifica un ID de sistema de dos dígitos asignado a un TCP / IP FOR Partición VSE. Cuando inicia una partición TCP / IP FOR VSE, puede usar la cadena de parámetro en la instrucción EXEC para especificar una identificación del sistema. Cuando usa la palabra clave ID en el Macro SOCKET, todas las solicitudes SOCKET se transmiten a la partición TCP / IP FOR VSE que coincide con la ID que usted especificar. El valor predeterminado es 00.

LOPORT= [0|localportnum]

Identifica el número de puerto local que se utilizará cuando establecer una conexión TCP. Si especifica 0, que es el valor predeterminado, TCP / IP FOR VSE asigna un puerto local disponible número. La asignación comienza en 4096 y continúa hacia arriba. Los números de puerto no deben reutilizarse con la misma IP direcciones durante al menos varios minutos. Esto asegura que el rancio los datagramas de una conexión cerrada no contaminan más tarde conexión. En general, los clientes (ACTIVE = YES) deberían especifique 0 y los servidores (ACTIVO = NO) deben especificar el número de su puerto conocido.

6


Keyword Descripción MF=[E|L] Establece el formato macro. Especifique L para crear el global

área constante y E para ejecutar todas las demás funciones. los el valor predeterminado es E.

MFG=soparea Identifica la dirección del área de parámetros SOCKET, que se utiliza para pasar las direcciones de la solicitud parámetros a TCP / IP PARA VSE. Para hacer tu programa totalmente reentrante, puede definir el área en la que desea la lista de parámetros a construir. La longitud de esta área es 72 bytes Se puede reservar utilizando el siguiente código: SOPAREA DS (SOPLEN)X PARAMETER AREA

No hay defecto. NEGOT=[YES|NO] Indica si las conexiones TELNET están permitidas negociar

atributos de sesión. Cuando especifica YES, se permite la negociación. El valor predeterminado es YES.

TIMED=[YES|NO] Indica si esta operación de socket está sujeta a TIEMPO DE ESPERA = valor. Cuando especifica SÍ, la supervisión es activado. Si el tiempo especificado en la palabra clave TIMEOUT transcurre sin recibir datos del host remoto, la recepción se publica como completa y el control vuelve a programa de llamadas. Esto es especialmente útil para limitar RECIBIR y Pasivo ABRIR (escuchar) solicitudes de socket, que puede requerir una cantidad de tiempo indefinida para completar. El valor predeterminado es NO.

TIMEOUT= [36000|timevalue]

Especifica el tiempo permitido para que la pila responda a una solicitud de socket. El valor es el número de 300 segundos intervalos. Un valor de 18000 especifica 60 segundos. El valor predeterminado es 36000, o 2 minutos.

USESYS= [YES|NO]

Indica si el JCL de la aplicación puede usar el // OPTION SYSPARM = xx para identificar el TCP / IP Para la partición VSE para conectarse. En caso afirmativo, la declaración es permitida. Si se ha emitido el comando SET_SYSID, USESYS = YES lo anula. El valor predeterminado es NO.

WAIT=[YES|NO] Indica si la macro SOCKET debe generar un ESPERA apropiada para la finalización de la operación. Si SÍ, se genera una ESPERA. Si NO, la macro SOCKET se completa tan pronto como la solicitud se haya puesto en cola partición de pila En este caso, debe codificar un WAIT separado para asegurar que la operación se complete. El valor predeterminado es NO.

7


Área Global Constant El área Global Constant es necesaria para todas las operaciones macro de SOCKET dentro de una aplicación. Esta área contiene información constante requerida por todas las operaciones SOCKET para comunicación con TCP / IP FOR VSE dividir. La siguiente macro SOCKET crea el área constante global y establece la ID de la partición TCP / IP FOR VSE deseada:

label SOCKET ID=00,MF=L Conectando a TCP/IP TCP / IP FOR VSE puede ejecutarse en múltiples particiones a la vez. Usar la FOR VSE macro SOCKET, debe identificar una pila específica de TCP / IP FOR VSE identificación en el área global constante. Para cambiar la partición que eres comunicando con, debe modificar esta área. El seguimiento la instrucción muestra cómo cambiar el identificador de pila TCP / IP FOR VSE a que conecta tu aplicación.

label SOCKET SET_SYSID,newid En esta declaración, newid se refiere a un área de dos bytes que contiene el nuevo ID de pila para operaciones SOCKET. Todas las operaciones de SOCKET que siguen se dirigen a la pila especificada. Por ejemplo, usando

SOCKET SET_SYSID,=C'01' se conecta a la partición que ejecuta el ID de pila 01. (Por supuesto, en lugar de usar = C'01 ', puede especificar un nombre de campo de dos bytes que contenga el valor. La macro no realiza ninguna comprobación de longitud.) Especificar USESYS = YES en una solicitud de apertura SOCKET anula la especificación SET_SYSID si un // OPTION SYSPARM = '01 'se usa en el JCL de la partición ejecutando la aplicación.

Códigos Return El registro 15 contiene los códigos de retorno. Debes consultar el código de retorno después de cada llamada SOCKET para determinar si su solicitud se procesó exitosamente. Los códigos se definen con ecuaciones en la macro SOCKET.

Debe determinar si el registro 15 contiene cero o un valor distinto de cero valor. Si se devuelve cero, esto significa que ha podido usar el interfaz. No significa que su solicitud haya sido exitosa. Debes espere a que la pila devuelva una respuesta emitiendo un WAIT contra el Campo SRECB. Después de publicar el SRECB, verifique el código de retorno en el Campo SRCODE que está contenido en el área de respuesta SRBLOK. Esta El valor indica si la solicitud se realizó correctamente. Los valores de SRCODE son explicados en la siguiente sección.

Si el registro 15 contiene un valor distinto de cero, significa que su solicitud de socket No se pudo programar. Esto puede indicar inválido o inconsistente parámetros, errores lógicos o que la partición de pila solicitada no es disponible. Para algunos códigos de retorno de registro 15, también debe examinar el valor en el registro 0. Este valor puede indicar el problema específico.

8


El registro 15, el registro 0 combinaciones de códigos y sus significados son

descrito en la siguiente tabla.

Valor Reg 15

Valor Reg 0

Significado

0 La solicitud se ha programado correctamente. Después de la ECB = el campo está publicado, SRCODE contiene el estado de finalización.

4 x Falta de almacenamiento. El registro 0 contiene el código de retorno de la llamada de almacenamiento (GETVIS).

8 La pila solicitada no está disponible. Ver el registro 0 valor (1, 2 o 3).

1 SCBLOK no se encontró. Esto indica que TCP / IP FOR VSE no se ha inicializado desde la última IPL.

2 La pila no se está ejecutando o se está cerrando.

3 El eyecatcher SQBLOK está mal. Esto indica corrupción en uno de los bloques de control TCP / IP clave. Es posible que deba realizar un ciclo de la partición de la pila para recuperarse.

9 2 El eyecatcher SCBLOK está mal. Esto puede indicar un problema de corrupción de almacenamiento con una crítica Bloque de control TCP / IP. Ciclar uno de los TCP / IP las pilas FOR VSE pueden corregir el problema.

10 3 El puntero SQBLOK en SCBLOK es cero. Esta significa que la solicitud de socket no pudo encontrar una pila activa con un valor SYSID coincidente.

11 4 La pila se está cerrando.

12 El campo DESCRIPTOR es cero (excepto OPEN)

14 6 El campo SOQUEUE en SOWORK es cero. Esto puede indicar que la llamada de socket se emitió (1) antes de ABIERTO completada, (2) después de que se emitió un CIERRE, o (3) con un valor DESCRIPTOR no válido.

15 1 El campo SQSOCKET en SQBLOK es cero. Esta generalmente significa que la pila se está inicializando.

16 x No se puede obtener almacenamiento. El registro 0 contiene el Código de retorno de GETVIS.

17 x Error de liberación de almacenamiento. El registro 0 contiene el Código de retorno de FREEVIS o IPSTOR.

9


Valor Reg 15

Valor Reg 0

Significado

24 x La llamada SUBSID falló. El registro 0 contiene el Código de retorno SUBSID.

28 La lista de parámetros SOPARM no es válida. Ver el registrar el valor 0 (1, 2, 3 o 4).

1 El eyecatcher ("SO") no es válido.

2 La versión no es válida (no 1).

3 La versión no es válida (no 2, 3 o 4).

4 El campo descriptor es cero (todas las llamadas).

SRBLOK DSECT Cada solicitud de SOCKET genera una respuesta que se devuelve en un byte de

56 áreas que usted proporciona. La primera palabra completa de esta área sirve

como BCE eso permite que el programa de aplicación espere a que se complete

la solicitud.

El formato del SRBLOK se puede encontrar en la macro SRBLOK y es sujeto a

cambios de lanzamiento a lanzamiento. Por lo general, se agregan nuevos

campos hasta el final del bloque por compatibilidad.

Los campos DSECT se describen en la siguiente tabla.

Field Descripción

SRECB Esta palabra completa es el BCE primario para la operación de solicitud. Cuando se completa la solicitud SOCKET, se publica el BCE. La macro SOCKET también proporciona un mecanismo para publicar un segundo BCE junto con El SRECB. El segundo BCE no está contenido dentro del área de respuesta.

SRLOPORT Después de completar una solicitud abierta, esta media palabra contiene el puerto local número asignado a la conexión.

SRFOPORT Una vez que se completa una solicitud abierta, esta media palabra contiene los números de puerto asignado a la conexión.

SRFOIP Después de completar una solicitud abierta, esta palabra completa contiene la IP extranjera Dirección del sistema de conexión.

SRCOUNT Una vez que se completa una solicitud de recepción, este campo de media palabra contiene la cantidad de bytes que fueron transferidos.

SRFLAGS Estas banderas alertan al programa de aplicación sobre una acción específica u operación que ha ocurrido. Se discuten con más detalle donde necesario.

10


Field Descripción

SRCODE Este campo contiene el código de retorno para cada solicitud SOCKET. Los códigos y sus significados se enumeran a continuación. El equivalente hexadecimal de cada El código está entre paréntesis.

Código Significado

0 (0) La solicitud de socket se completó normalmente.

4 (4) Conexión no encontrada (no se aplica a ABIERTO). La conexión ha terminado y los bloques de control relacionados son ir. Para un RECIBO, esto significa que el problema del host remoto emitió un FIN y se recuperaron todos los datos de la conexión.

8 (8) La conexión ha sido RESET.

12 (0C) Un OPEN o RECEIVE cronometrado alcanzó el tiempo de espera especificado valor sin completar.

16 (10) El campo descriptor contiene nulos. Esta solicitud debería tener No se pudo programar. Esto puede indicar un uso incorrecto del SOCKET macro u otra API.

20 (14) Uso duplicado de un BCE. Esta solicitud comparte un BCE y SRBLOK con otra solicitud de socket en ejecución.

24 (18) Falla general durante una APERTURA.

28 (1C) La pila TCP / IP FOR VSE se está cerrando.

32 (20) Para una llamada de ESTADO, el área de retorno es demasiado corta para devolver el STATBLK

36 (24) Se emitió un ENVIAR después de un CIERRE o una FIN.

40 (28) La conexión no se estableció cuando un ENVIAR o un RECIBO fue emitido.

44 (2C) Se emitió un CIERRE, pero todavía había datos en espera de ser recibido (por un RECIBO). Los datos en cola se descartan.

48 (30) Hubo una escasez de almacenamiento en la partición TCP / IP FOR VSE.

52 (34) La operación se terminó porque se emitió un ABORT.

SRTERMTY Contiene el tipo de terminal acordado después de una solicitud de apertura TELNET negociado

11


Abrir una Conexión Antes de poder comunicarse, debe abrir una conexión. UNA La conexión puede ser activa o pasiva. Una conexión activa busca el socio especificado y negocia activamente la conexión. Un pasivo la conexión no toma medidas y simplemente espera recibir una conexión solicitud del extremo remoto.

Conexión activa El siguiente ejemplo abre una conexión activa.

label SOCKET OPEN,TCP, * ACTIVE=YES, * FOIP=IPADDR, * FOPORT=65, * DESC=SOCKDESC, * ECB=RESULTS LTR R15,R15 Test the return BNZ ERROR Failure, then... WAIT RESULTS USING SRBLOK,RESULTS CLI SRCODE,0 BNE ERROR

En este ejemplo, se le pide a TCP / IP FOR VSE que establezca una conexión con un sistema externo cuya dirección IP se encuentra en la palabra completa IPADDR y cuyo número de puerto extranjero es 65. Una vez establecida la conexión, la palabra completa SOCKDESC debe pasarse a todas las llamadas SOCKET posteriores para esta conexión Esta es la única llamada que se requiere para establecer un Conexión completa con el sistema extranjero.

Después de publicar el SRECB contenido en el área de resultados, la conexión es Listo para enviar y recibir actividad. Una solicitud de conexión activa debe completar dentro de un período de tiempo de espera. La palabra clave timeout se omite, por lo que el valor de tiempo de espera predeterminado es de dos minutos. Si la conexión no es completar en dos minutos, se publica el SRECB y aparece un error La condición se establece en el campo SRCODE del área de resultados.

Conexión pasiva El siguiente ejemplo abre una conexión pasiva.

label SOCKET OPEN,TCP, * PASSIVE=YES, * LOPORT=65, * DESC=SOCKDESC, * ECB=RESULTS LTR R15,R15 Test the return BNZ ERROR Failure, then... WAIT RESULTS USING SRBLOK,RESULTS CLI SRCODE,0 BNE ERROR

12


En este ejemplo, el programa de aplicación dirige TCP / IP FOR VSE a escuche una solicitud de conexión para llegar al puerto 65. Cuando una conexión llega la solicitud, se completa la conexión y la solicitud se publica como completar.

Tenga en cuenta que el puerto extranjero y la dirección IP no están especificados. Esto permite cualquier solicitud de conexión de usuario remoto para ser aceptada.

Después de que se establece la conexión, más solicitudes de conexión para esto el número de puerto local se rechazan a menos que haya otros programas de servidor esperando en este mismo número de puerto local. En este ejemplo, la escucha la conexión establecida espera para siempre una solicitud de conexión. Si esto es no deseable, TIMEOUT = puede usarse para forzar una finalización incluso si no Se recibe la solicitud de conexión.

Receiving Data Una vez que se completa una conexión, el siguiente paso lógico es recibir o enviar datos. El siguiente ejemplo usa la macro SOCKET para recibir datos de un anfitrión extranjero.

label SOCKET RECEIVE,TCP, * DATA=(INBUFF,INLEN), * DESC=SOCKDESC, * ECB=RESULTS LTR R15,R15 Test the return BNZ ERROR Failure, then... WAIT RESULTS USING SRBLOK,RESULTS CLI SRCODE,0 BNE ERROR MVC INGOT(2),SRCOUNT . . . INBUFF DC A(BUFFER) INLEN DC F'4096' INGOT DC H'0' BUFFER DS CL4096

En este ejemplo, la macro SOCKET pone en cola una solicitud para recibir

información del anfitrión extranjero. Puede tener muchas solicitudes de

recepción en cola en la misma conexión. Cada solicitud debe proporcionar su

propio área de resultados separada (BCE =), pero debe referirse a la misma

palabra del descriptor (DESC =). Cada solicitud se procesa en el orden en que se

puso en cola y los datos se pasa a la aplicación cuando llega. La máxima

información que se puede recibir en una solicitud de 65.535 bytes. Porque es

inusual para 64K de información para llegar a la vez, tal especificación

desperdicio de memoria. Generalmente, la información se recibe en piezas no

mayores que el tamaño de MTU del enlace. La cantidad de datos recibidos se

devuelve en el campo SRCOUNT

13


Es importante tener en cuenta que TCP es un protocolo orientado a la transmisión, y La iteración es necesaria cuando se recibe una secuencia de datos. Esto es una diferencia significativa de la mayoría de las operaciones de I/O VSE y solicita que están orientados al registro o al bloque. Una operación de I/O de disco o cinta VSE emite una solicitud de lectura, espera a que el BCE se complete, verifica si hay errores, y luego tiene todo el registro o bloque disponible para su procesamiento. Un TCP la aplicación de flujo puede enviar 4096 bytes de datos a un receptor solicitud. La aplicación receptora puede obtener los 4096 bytes completos en uno recibir, o puede obtener 2000 bytes, luego 1000 bytes y luego 1096 bytes en tres solicitudes de recepción separadas. TCP garantiza que entrega bytes en secuencia, pero no garantiza que entregue bytes en los mismos grupos en los que se envían.

Para manejar un flujo de datos TCP, la aplicación receptora debe continuar emitir solicitudes de recepción a la secuencia de entrada hasta los datos acordados La estructura indica que se reciben todos los datos. Por ejemplo, TELNET y Los protocolos FTP utilizan un indicador de retorno de carro / avance de línea en el flujo de datos para indicar el final de un comando o registro.

La aplicación receptora continúa recorriendo las solicitudes de recepción y para agregar datos a un búfer hasta que los indicadores de retorno de carro / avance de línea estén detectado en el flujo de datos. En ese punto, la aplicación receptora sabe que ha recibido un comando o registro completo que puede ser procesado. Debe preservar cuidadosamente los datos sobrantes, ya que este es el primer parte del próximo disco.

Sending Data El siguiente ejemplo utiliza la macro SOCKET para enviar datos a través de una conexión.

MVC OUTLEN(4),=F'45' SOCKET SEND,TCP, * DATA=(OUTBUFF,OUTLEN), * DESC=SOCKDESC, * ECB=RESULTS LTR R15,R15 Test the return BNZ ERROR Failure, then... WAIT RESULTS USING SRBLOK,RESULTS CLI SRCODE,0 BNE ERROR . . . OUTBUFF DC A(BUFFER) OUTLEN DC F'4096' BUFFER DS CL4096

En este ejemplo, se envían 45 bytes de datos a través de la conexión al sistema

extranjero El SRECB se publica en el área de resultados cuando los datos tienen

Llegó a la ubicación deseada. La solicitud de envío debe referirse a palabra

descriptiva (DESC =) que se creó durante el procesamiento ABIERTO.

14


Las solicitudes de envío se procesan en el orden en que se emiten. El tamaño máximo de búfer que se puede usar es 65.535 bytes. A pesar de tamaño, cada solicitud de envío aceptada por la partición TCP / IP FOR VSE es roto en piezas de diferentes tamaños para la transmisión real.

Para acelerar la transmisión de datos, es posible que no desee esperar cada ENVIAR Solicitud de confirmación por parte del host remoto antes de continuar. En esto caso, llenarías un búfer grande, enviarías un ENVÍO (sin esperar), rellenarías el búfer y luego espere a que se complete el primero. Para el máximo eficiencia, use dos áreas BCE = y altérnelas. Esto asegura que siempre hay datos listos para ser enviados.

Status A veces necesita obtener información sobre una conexión u operación previa a su finalización. Para hacer esto, use la llamada ESTADO.

SOCKET OPEN,TCP, * DESC=DATADESC, * PASSIVE=YES, * ECB=DATAECB LTR R15,R15 BNZ PASVF421 * * Wait for 1 second * PASVLIST XC PASVTECB(4),PASVTECB SETIME 1,PASVTECB WAIT PASVTECB * * Let's do a status call * LA R1,PASVCCBL ST R1,PASVADDR MVC PASVLEN(4),=A(STBLOKLN) SOCKET STATUS,TCP, * DESC=DATADESC, * DATA=(PASVADDR,PASVLEN), * ECB=PASVRECB LTR R15,R15 BNZ PASVF421 LA R1,PASVRECB WAIT (1) USING SRBLOK,PASVRECB CLI SRCODE,SRSTGOOD BNE ERROR * * Check that the connection... * USING STATBLK,PASVCCBL LA R5,60 TRYAGIN DS 0H CLI STSTATE,STSTLIST BE GOTPORT LA R3,TIMEECB SETIME 2,TIMEECB WAIT TIMEECB BCT R5,TRYAGIN

15


En este ejemplo, se usa una llamada de estado para determinar el número de puerto local que fue asignado y la dirección IP local de TCP / IP FOR VSE. El local el número de puerto podría haberse determinado cuando el primer cliente extranjero conectado a la aplicación del servidor VSE. Cuando el servidor VSE la aplicación emite un ABIERTO pasivo, el programa de aplicación puede esperar hasta que se conecte un cliente extranjero y se complete la OPEN. En este punto, el área de resultados contiene el número de puerto local (SRLOPORT), el extranjero número de puerto (SRFOPORT) y la dirección IP extranjera (SRFOIP).

Para algunas aplicaciones de servidor, por ejemplo, FTP, debe conocer el número de puerto local o la dirección IP local antes de que los clientes estén conectados. Además, la dirección IP local no se devuelve en el área de resultados y debe ser obtenido por una llamada de estado.

En el ejemplo anterior, emitimos una solicitud de estado ante cualquier cliente extranjero nos hemos conectado a nuestra aplicación de servidor VSE y guardamos el puerto local número y dirección IP local de VSE después de que la conexión esté escuchando estado.

Un ejemplo de una aplicación que usa una llamada de estado es el protocolo FTP. Utiliza una conexión de control y una conexión de datos en diferentes puertos. La conexión de control suele estar en el puerto 21 estándar y en clientes extranjeros conéctate allí. Cuando un usuario pone u obtiene un archivo, sin embargo, un se abre una conexión de datos separada y se emite una llamada de ESTADO a determine el número de puerto asignado a la conexión de datos. Después del puerto se determina el número, el comando del puerto FTP se envía en el control conexión al cliente extranjero para que sepa el número de puerto asignado a la conexión de datos. El cliente extranjero abre su lado de los datos. Conexión, y los comandos FTP pueden continuar siendo enviados y recibidos en la conexión de control (teóricamente) incluso mientras se está utilizando un archivo grande transferido en la conexión de datos separada.

Puede usar la macro STATBLK para asignar información devuelta de un Llamada de estado. La macro STATBLK reemplaza completamente al CCBLOK macro que se distribuyó con versiones anteriores de TCP / IP FOR VSE. Por compatibilidad, agregando el parámetro "CC = YES" a la macro STATBLK la llamada iguala los antiguos nombres de campo CCBLOK a su STATBLK contrapartes

STATBLK DSECT STATBLK DSECT asigna el bloque de control de conexión desde Partición TCP / IP FOR VSE al almacenamiento local de la persona que llama. Contiene muchos campos destinados al uso interno y que no son útiles en esta situación. Los campos enumerados en la siguiente tabla son útiles.

Field Descripcion

STSTATE Estado de conexión STLOIP Dirección IP local STLOPORT Número de puerto local

16


Field Descripcion

STFOIP Dirección IP extranjera

STFOPORT Número de puerto extranjero

Close Connection Después de que termine de usar una conexión, debe cerrarla. El seguimiento El

ejemplo muestra una operación de cierre:

SOCKET CLOSE,TCP, * DESC=DATADESC, * ECB=DATAECB LTR R15,R15 BNZ ERROR * * Wait for completion * WAIT (1) LA R1,DATAECB USING SRBLOK,DATAECB CLI SRCODE,0 BNE ERROR

Esta es una operación simple que solo requiere un descriptor y un resultado

zona. Aunque la operación de cierre está en cola detrás de cualquier pendiente

enviar operaciones, es una buena práctica permitir solicitudes previamente en

cola completar antes de emitir el cierre.

17


Conexión de control

Hemos discutido cómo puede usar la macro SOCKET para TCP conexiones

También puede usarlo para comunicarse directamente con TCP / IP FOR VSE, que

mantiene un administrador de control en su partición. Utilizando el Instalación

SOCKET, puede enviar solicitudes al Administrador de control y obtener los

resultados

Resolviendo Symbolic TCP / IP FOR VSE contiene un servidor de nombres local (consulte DEFINIR Names NOMBRE en la referencia de comando TCP / IP FOR VSE) y un cliente de nombre de dominio (vea el comando SET DNS1). Esto le permite asignar símbolos n nombres a direcciones TCP / IP reales. Los nombres simbólicos son más fáciles de recuerde que las direcciones IP, y puede reasignar un nombre a otro habla a.

Para solicitar la dirección IP asociada con un nombre simbólico, envíe el siguiente

comando al administrador de control:

GETHOSTBYNAME name

El administrador de control busca el nombre en el servidor de nombres local y

luego en el cliente de nombre de dominio, y devuelve este bloque de datos:

IPADDR DS F IP Address in binary IPADDRC DS CL15 IP Address in display format

Puede solicitar una dirección IP o nombre de host utilizando los comandos

descrito en la siguiente tabla. La entrada de texto debe contener el comando y

operando y deben delimitarse con una nueva línea (x15). Los comando y los

datos del operando deben estar separados por uno o más espacios en blanco.

Comando Entrada Salida

GETHOSTBYADDR Dirección IPv4 en Texto EBCDIC caracteres

Dominio delimitado en blanco nombre

GETHOSTBYNAME Nombre de dominio en EBCDIC caracteres de texto

19 bytes de datos que contienen: • Dirección binaria IPv4 de 4 bytes • Dominio IPv4 de texto de 15 bytes dirección (nnn.nnn.nnn.nnn)

GETHOSTNAME Ninguna Nombre de texto delimitado en blanco del sistema local de VSE

18


Comando Entrada Salida

GETHOSTID Ninguna 19 bytes de datos que contienen: • Dirección binaria IPv4 de 4 bytes • Dirección IPv4 de texto de 15 bytes del sistema local de VSE

Al igual que todas las operaciones de SOCKET, el primer orden del día es abrir

una conexión. Esto se muestra en el siguiente ejemplo.

HOSTNAME SOCKET OPEN,CONTROL, Open the connection * DESC=CONTDESC, Descriptor * ECB=CONTECB ECB Address LTR R15,R15 Test the return code BNZ ERROR Bad, then error LA R1,CONTECB Address the ECB WAIT (1) * * * Check the results * USING SRBLOK,R1 CLI SRCODE,SROPGOOD Was the open good? BNE ERROR If no, exit with error DROP R1

En este punto, se establece la conexión y el administrador de control está

esperando que la aplicación transmita un comando para su ejecución. Sin IP la

dirección o la información del puerto se especifica en la llamada abierta. Esto es

porque No es necesario conectarse a un host extranjero. La única conexión

requerido es con la partición TCP / IP FOR VSE.

El siguiente paso es codificar el comando que se pasará al control gerente. Esto

se muestra en el siguiente ejemplo.

* * Set up the command MVC CONTBUFF(CMDL),CMD Move command to buffer LA R3,CMDL Command length (w/NL) ... CMD DC C'GETHOSTBYNAME CSI-INTERNATIONAL.COM' DC X'15' End-of-command (NL) CMDL EQU *-CMD Length of entire cmd

Tenga en cuenta que un carácter de fin de comando (una nueva línea EBCDIC) es

incluido.

19


A continuación, envíe el comando al administrador de control. Haces esto

exactamente como si los datos están destinados a un host extranjero.

* * * Send the command ST R3,CONTLEN Save the length LA R4,CONTBUFF Address the buffer ST R4,CONTADDR Save the address SOCKET SEND,CONTROL, Send the command * DATA=(CONTADDR,CONTLEN), Identify the data * DESC=CONTDESC, Descriptor * ECB=CONTECB ECB Address LTR R15,R15 Test the return code BNZ ERROR Bad, then error LA R1,CONTECB Address the ECB WAIT (1) * * * Check the response USING SRBLOK,R3 CLI SRCODE,SRSEGOOD Was the send good? BNE ERROR No, then exit w/error DROP R1

En este punto, el administrador de control ha recibido el comando y está

ejecutándolo Los resultados del comando se devuelven como datos.

Para obtener los resultados, emita una solicitud de recepción. Aunque puedes

emitir el recibir antes del envío (dejándolo en cola), el siguiente ejemplo muestra

emitió en secuencia:

* * * Let's get the response MVC CONTLEN(4),=F'100' Set the length LA R4,CONTBUFF Address the buffer ST R4,CONTADDR Save the address SOCKET RECEIVE,CONTROL, Receive the response* DATA=(CONTADDR,CONTLEN), Identify the data * DESC=CONTDESC, Descriptor * ECB=CONTECB ECB Address LTR R15,R15 Test the return code BNZ ERROR Bad, then error LA R1,CONTECB Address the ECB WAIT (1) * * * Check the results * USING SRBLOK,R1 CLI SRCODE,SRREGOOD Was the receive good? BNE ERROR No, then exit w/error DROP R1

Ahora que ha recibido los resultados de la ejecución del comando, usted puede

extraerlos de la respuesta.

20


Esto se muestra en el siguiente ejemplo:

* * * Copy the data from the buffer MVC IPADDR(4),CONTBUFF Copy the IP Address MVC IPADDRC(15),CONTBUFF+4 Copy the Char IP Addrs

Ahora debe emitir una operación de cierre para finalizar la conexión con El

gerente de control. Si deja la conexión abierta, puede hacer solicitudes

adicionales a través de la misma conexión. Puedes cerrar la conexión como se

muestra en el siguiente ejemplo:

* * * Close the control SOCKET CLOSE,CONTROL, Close the connection * DESC=CONTDESC, Descriptor * ECB=CONTECB ECB Address LTR R15,R15 Test the return code BNZ ERROR Bad, then OK, move on LA R1,CONTECB Address the ECB WAIT (1)

21


Programas de muestra

El código fuente de los siguientes programas de muestra se puede descargar del

sitio web de CSI International, www.csi-international.com.

Programa Descripción

Servidor de ensamblador SAMSERVR

Este programa de servidor de muestra está escrito en ensamblador idioma y realiza las siguientes tareas: • Inicializa y adjunta tres sub tareas VSE • Abre una conexión TCP pasiva y espera un comando desde una aplicación cliente • Envía una de las sub tareas de VSE adjuntas a procesa el comando y envía una respuesta al cliente aplicación que envió el comando

Cliente ensamblador SAMCLINT

Este programa cliente de muestra está escrito en ensamblador idioma y realiza las siguientes tareas: • Abre una conexión TCP activa al servidor • Lee un comando de SYSIPT • Envía el comando al servidor • Emite una recepción para la respuesta y muestra la respuesta en SYSLST

Microsoft Visual Basic Cliente para Windows®

Este cliente de muestra realiza las siguientes tareas: • Abre una conexión TCP activa a SAMSERVR en VSE • Muestra una interfaz GUI de Windows para enviar comandos para VSE • Envía un comando desde la GUI de Windows a VSE • Muestra la respuesta VSE en un formato de vista de lista en el GUI de Windows

22

http://www.csi-international.com/

2 2. BSD Socket Interface

Visión general

La interfaz de programación de aplicaciones estándar de facto (API) para Las

aplicaciones TCP / IP es la interfaz de socket BSD. Aunque esta API fue

desarrollado para el sistema operativo BSD Unix a principios de la década de

1980, tiene implementado en una amplia variedad de sistemas que no son Unix.

Para TCP / IP PARA VSE, la interfaz de socket BSD simplemente se conoce como

BSD interfaz.

No había un estándar oficial de RFC para la interfaz BSD para IPv4, pero RFC3493,

"Extensiones básicas de interfaz de socket para IPv6", ahora contiene una

definición estándar para IPv6 y aborda la compatibilidad con el IPv4 de estándar

de facto. La implementación de VSE de la interfaz no proporciona todas las

variaciones de las funciones definidas, pero intenta paralelamente las interfaces

z / VM y z / OS según sea necesario.

Idiomas La interfaz BSD se puede utilizar en C, ensamblador (a menudo denominado

Lenguaje básico de ensamblador, o BAL), COBOL y otros idiomas que admite

convenciones de enlace de llamada / guardado estándar. También es válido para

su uso con programas por lotes o CICS. La interfaz determina en tiempo de

ejecución si el programa está bajo el control de CICS y, si lo está, usa CICS

servicios. El entorno del lenguaje (LE) también se detecta dinámicamente para

aplicaciones conformes a LE.

23

Chapter 2 BSD Socket Interface

Que es un Socket?

La interfaz BSD es el estándar universalmente aceptado para escribir clientes y aplicaciones de socket de servidor que usan el protocolo TCP / IP. Aplicaciones El uso de la interfaz BSD se conoce comúnmente como aplicaciones de socket. Hay mucha información disponible sobre cómo crear aplicaciones de socket usando las funciones bien conocidas de la interfaz. Antes de comenzar a usar estos funciones para desarrollar aplicaciones de socket, debe comprender el Concepto de un zócalo.

Definición El término socket se ha utilizado de muchas maneras, y es importante Comprender el significado dentro del contexto de TCP / IP PARA EL BSD DE VSE interfaz. Un socket es un bloque de control asignado dinámicamente que es asignado un número de socket único. Una aplicación pasa el zócalo número a varias funciones (escuchar, aceptar, enviar, recibir, cerrar, etc.) para controlar una sola conexión TCP / IP. En esencia, el número de socket es un controlador que permite que la aplicación funcione independientemente de TCP / IP estructuras de bloques de control.

El número de socket se asocia dinámicamente con un puerto específico cuando Se establece la conexión. Puede usar un socket para solicitar información de TCP / IP, espere una solicitud de conexión entrante o enviar y recibir datos a través de la red. Un número de socket único es requerido para cada conexión utilizada por una aplicación. Cuando la aplicación cierra la conexión, el número de socket (y el correspondiente bloque de control de socket) se devuelve al grupo de sockets disponibles.

Socket vs. Port El término socket a veces se confunde con el número de puerto. En esto discusión de la interfaz BSD, los dos términos tienen completamente diferente significados Esta diferencia puede ser más fácil de entender al describir cada término en el contexto de un servidor BSD y una aplicación cliente.

En una aplicación de servidor BSD, la función de socket se utiliza para asignar y Asignar un número de socket único. La función de vinculación se utiliza para asocie ese número de socket con un puerto TCP / IP específico. El BSD el servidor tendría múltiples conexiones con clientes remotos usando un único números de socket, pero tendría el mismo número de puerto para todos los clientes conexiones El número de puerto para un servidor suele ser una constante entre 1 y 65.535 que conocen las aplicaciones cliente que desean conectarse al servidor En comparación, los números de socket son únicos entre 1 y 8.192 y solo los conoce la aplicación del servidor.

En una aplicación de cliente BSD, la función de socket también se usa para Asignar dinámicamente y obtener un número de socket único. El connect () Luego se llama a la función con una dirección IP remota y un número de puerto parámetros La aplicación cliente debe conocer u obtener el número de puerto de la aplicación del servidor antes de que emita su solicitud de conexión.

24


El número de puerto local de una aplicación cliente generalmente se asigna

dinámicamente, y la mayoría de las aplicaciones de clientes no saben ni les

importa qué Se utiliza el número de puerto. Simplemente usan el zócalo

asignado dinámicamente número y número de puerto remoto para comunicarse

con el servidor remoto solicitud. El cliente realmente solo necesita saber la

dirección IP y el puerto número de la aplicación del servidor remoto para

conectarse a ella.

25


Usando las funciones de Socket

Las funciones de socket permiten que los programas de aplicación se comuniquen con el Partición TCP / IP PARA VSE. Puede usar las funciones de socket para ambos aplicaciones de servidor y cliente. Los ejemplos en esta sección muestran el orden en el que se llaman varias funciones de socket para que pueda ver cómo funcionan las funciones en un programa de socket BSD. Esta sección también incluye información sobre cómo conectarse a una pila TCP / IP FOR VSE específica.

Los ejemplos a continuación no son detallados pero transmiten una comprensión general de los conceptos involucrados. Cada función se describe en una sección posterior.

Servidor TCP Una aplicación típica de servidor TCP tomará las siguientes acciones:

• Asignar un socket con una llamada socket ().

• Inicialice la estructura sockaddr solo con el número de puerto deseado. El resto de la dirección IP se borra a ceros.

• Enlace el socket asignado a un número de puerto específico con una llamada bind ().

• Emitir una llamada listen () para enviar la solicitud de apertura pasiva inicial al Partición TCP / IP PARA VSE.

• Emitir una llamada accept () para que el servidor espere (bloquee) hasta que un cliente conecta Cuando una aplicación cliente envía una solicitud de conexión al puerto del servidor, la aceptación asigna un nuevo socket para el cliente, vuelve a emitir la pasiva se abre en el número de socket original y luego devuelve control a la aplicación del servidor BSD con el nuevo número de socket.

• Procese la solicitud del cliente realizando las siguientes acciones:

1. Emita una llamada a reciben () para recuperar los datos del cliente.

2. Procesar los datos del cliente.

3. Emita una llamada send () para responder al cliente.

4. Emita una llamada close () para cerrar el nuevo socket.

• Regrese a la llamada accept () para esperar la solicitud de otro cliente.

• Emitir una llamada close () cuando el servidor se apaga para cerrar el original socket y terminar la aplicación del servidor.

Cliente TCP Una aplicación de cliente TCP típica tomará las siguientes acciones:

• Obtenga un número de socket con una llamada socket ().

• Conéctese a un host remoto con una llamada connect () utilizando el socket número obtenido de la llamada socket ().

26


• Enviar datos al host remoto con una llamada send () utilizando el mismo socket

número que se usó para connect () y se obtuvo del llamada socket ().

• Emitir una llamada de recepción () para esperar una respuesta usando el

mismo número de socket que se usó para la solicitud send ().

• Procesar los datos recibidos.

• Cierre la conexión utilizando el mismo número de socket que se utilizó para la

llamada connect ().

Conexión a TCP/IP Por defecto, su programa se conecta con la partición TCP / IP FOR VSE asignado a

la pila ID 00. La asignación de ID se realiza en el parámetro campo de la

instrucción TCP / IP FOR VSE EXEC. El valor predeterminado para ID es 00.

Si desea conectarse a una partición TCP / IP FOR VSE diferente para prueba u

otros fines, puede usar la función setsysid () para cambiar El ID de la pila. Esta

función se describe en la siguiente sección.

Otra forma de especificar una ID de pila es incluir la siguiente // OPCIÓN

declaración en el JCL de su programa:

// OPTION SYSPARM='01'

En este ejemplo, 01 es la ID de dos dígitos de la pila deseada.

Puede anular la ID predeterminada y la definida en el // instrucción OPTION

SYSPARM especificando una ID de pila en una costumbre fase de opciones ($

SOCKOPT). Puede crear esta fase modificando configuración por defecto.

Consulte el "Apéndice A: Fase de opciones de $ SOCKOPT" página 196, para

obtener detalles sobre la configuración de opciones en una fase de opciones

personalizadas.

27


Descripciones de funciones

Esta sección enumera y describe las funciones de socket y su retorno códigos El

punto de entrada para Assembler, COBOL y otros idiomas es También se

enumera para cada función. Para obtener información sobre la variable errno,

vea la sección "Manejo de errores" en la página 58.

abort( ) La función abortar () termina inmediatamente la conexión con un reinicio (RST)

Las solicitudes pendientes de envío o recepción también se rescinden y

publicado completo con un resultado negativo. Después de que se complete el

abortar (), la conexión está cerrada y el zócalo está disponible para ser

reutilizado. La sintaxis es la siguiente:

int abort(int); rc = abort(socket);

Las variables se describen en la siguiente tabla:

Variable Descripción rc El código de retorno. Un 0 indica que el aborto se completó

exitosamente. Un -1 indica un error y errno contiene la razón. socket El número de socket que se abortará.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRABRT punto.

accept( ) La función accept () acepta una solicitud de conexión de un cliente remoto y devuelve el número de socket que se utilizará para la sesión. La sintaxis es como sigue:

int accept(int,struct sockaddr *,int *); rc = accept(listen,&sockaddr,&length);

Las variables se describen en la siguiente tabla.

Variable Descripción rc El número de socket asignado a la sesión aceptada es devuelto Un

valor de -1 indica que un error tiene ocurrió, y la variable errno contiene adicional información.

listen El número de socket utilizado por una llamada listen ().

28


Variable Descripción sockaddr Apunta a una estructura sockaddr o NULL. Si un puntero es

siempre que contenga la dirección del host aceptado. length Apunta a un entero que contiene la longitud del Estructura

sockaddr. Este valor es obligatorio si sockaddr es especificado. El sistema reemplaza el contenido original de longitud con la longitud del sockaddr.

Notas de uso:

• No hay correspondencia entre el número de socket de escucha y el número de

socket de sesión devuelto.

• El control no se devuelve a su programa hasta que se solicita una sesión

recibido en el socket de escucha. Si no desea ser suspendido, use la función

select ().

• El protocolo UDP no reconoce la función accept ().

• Debe aceptar () sesiones con todos los solicitantes. Sin embargo, puedes cierre

las conexiones indeseables de inmediato.

Para Assembler, COBOL y otros idiomas, llame a la entrada IPNRACCP punto.

bind( ) La función bind () asigna una dirección IP o número de puerto a un socket.

int bind(int,struct sockaddr *,int); rc = bind(socket,&sockaddr,length);


Variable Descripción rc El código de retorno. Un 0 indica éxito. A -1 indica que ha ocurrido

un error, y la variable errno tiene más información. socket El número de socket a etiquetar. sockaddr Apunta a una estructura sockaddr que contiene un puerto y / o

Dirección IP. length La longitud de la estructura sockaddr.

Notas de uso:

• Si especifica el puerto 0 en una solicitud de enlace, el sistema asigna un Puerto.

29


• Esta función se ve afectada por la opción $ OPTBNDX en $ SOCKOPT. Consulte

el “Apéndice A: Fase de opciones de $ SOCKOPT”, página 196, para más detalles

sobre la configuración de opciones en una fase de opciones personalizadas.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRBIND punto.

close( ) La función close () cierra una conexión y libera asignaciones recursos El socket se

devuelve al sistema.

int close(int); rc = close(socket);


Variable Descripción rc El código de retorno. Un 0 indica que el cierre se completó

exitosamente. Un -1 indica que ha ocurrido un error, y la variable errno contiene más información.

socket El número de socket a cerrar.

Notas de uso:

• Si está leyendo desde un socket y lo cierra mientras los datos están pendiente,

la conexión se restablece en lugar de cerrarse. Esto alerta al otro host a una

condición de error. Esta situación ocurre solo con TCP conexiones y no con

conexiones UDP.

• Esta función se ve afectada por la opción $ OPTCNFW en $ SOCKOPT. Consulte



Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRCLOS punto.

30


connect( ) La función connect () establece una conexión con un cliente remoto o servidor.

La información de estado no se devuelve hasta que se completa la conexión.

int connect(int,struct sockaddr *,int); rc = connect(socket,&sockaddr,length);


Variable Descripción rc El código de retorno. Un 0 indica que la conexión Completado

satisfactoriamente. Un -1 indica que un error tiene ocurrió, y la variable errno tiene más información.

socket El número de socket que se utilizará para la conexión. sockaddr Apunta a una estructura sockaddr que contiene la dirección del

cliente o servidor remoto al que desea conectarse. Esta el valor puede ser NULL si la función bind () ya tiene proporcionó la información.

length La longitud de la estructura sockaddr. Este valor puede ser NULL si sockaddr es NULL.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRCONN punto.

getclientid( ) La función getclientid () devuelve el identificador por el cual la llamada la

aplicación es conocida por la partición TCP / IP FOR VSE. El cliente que se

devuelve se utiliza en las funciones givesocket () y takesocket ().

int getclientid(int domain,struct clientid *,int); rc = getclientid(domain,&clientid);


Variable Descripción rc El código de retorno. Un 0 indica que la función Completado


domain El dominio de la dirección solicitada. clientid Puntero a una estructura clientid que debe contener el

identificador.

Para Assembler, COBOL y otros idiomas, llame a la entrada IPNRGETC punto.

31


gethostbyaddr( ) La función gethostbyaddr () toma una dirección IP y devuelve el nombre

simbólico asociado a él.

unsigned long gethostbyaddr(char *,int,int); rc = gethostbyaddr(ipaddr,ipaddr_len,domain);


Variable Descripción rc El nombre simbólico asociado con una dirección IP, o un -1

Si no se encuentra la dirección. Ipaddr El puntero a la dirección IP. ipaddr_len La longitud de ipaddr en bytes. domain El puntero al soporte de dominio de dirección (AF_INET).

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGHBA punto.

gethostbyname( ) La función gethostbyname () busca un nombre simbólico y devuelve su Dirección

IP (red).

unsigned long gethostbyname(char *); rc = gethostbyname(&string);


Variable Descripción rc La dirección IP (red) asociada con el nombre o a -1 si no se

encuentra el nombre. string Una cadena de texto delimitada por cero.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGETN punto.

32


gethostid( ) La función gethostid () devuelve la dirección IP utilizada actualmente por TCP / IP

local para el host VSE.

unsigned long gethostid( ); ipaddr = gethostid( );

La dirección devuelta es la establecida por SET IPADDR mando. Esto también es

cierto para los hosts con múltiples hosts.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGETH punto.

gethostname( ) La función gethostname () adquiere el nombre asignado del host local, si uno

existe.

int gethostname(char *, int); rc = gethostname(&buffer,length);


Variable Descripción rc El código de retorno. Un 0 indica que el nombre del host local ha

sido devuelto Un -1 indica que un error tiene ocurrió o que no se asigna ningún nombre al host local.

buffer Apunta a un búfer en el que el nombre delimitado por cero es devuelto Bajo TCP / IP PARA VSE, este búfer debe estar en al menos 17 bytes de largo.

length La longitud del búfer.

La función determina el nombre del host local localizando el local dirección del

host según lo determinado por el comando SET IPADDR. La función luego

escanea la tabla de nombres que se creó con el comando DEFINE NAME, ID = xxx,

IPADDR = xxx hasta que encuentre una coincidencia para el local dirección del

anfitrión Si encuentra una coincidencia, devuelve la entrada del nombre

asociado.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGETA punto.

33


getpeername( ) La función getpeername () devuelve la dirección IP extranjera y el puerto de el

par conectado a un enchufe.

int getpeername(int, struct sockaddr *,int); rc = getpeername(socket,&sockaddr,length);




socket El número de socket. sockaddr Señala una estructura sockaddr que debe contener el Dirección IP

y puerto extranjeros. length La longitud de la estructura sockaddr en bytes.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGETP punto.

getsockname( ) La función getsockname () devuelve la dirección IP local y el puerto de un

enchufe.

int getsockname(int,struct sockaddr *,int); rc = getsockname(socket,&sockaddr,&length);


Variable Descripción Rc El código de retorno. Un 0 indica que la función completado


socket El número de socket. sockaddr Señala una estructura sockaddr que debe contener el Dirección IP

y puertos. length Apunta a una variable que contiene la longitud del sockaddr

estructura.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGETS punto.

34


getsockopt( ) La función getsockopt () actualiza el área de retorno y la longitud con el valor de

la opción solicitada.

int getsockopt(int *,int *,int *,char *,int *) rc = getsockopt(&p1,&p2,&p3,&p4,&p5)


Variable Descripción rc El código de retorno. Un 0 indica que la función se completó

exitosamente. Un -1 indica que ha ocurrido un error, y La variable errno tiene más información.

p1 Puntero al número de socket. p2 Puntero al nivel de código para la opción relacionada. p3 Puntero a la opción solicitada. p4 Puntero al área de retorno para el valor de la opción solicitada. p5 Puntero a la longitud del área de retorno.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGETO punto.

getversion( ) La función getversion () actualiza el área de retorno con la versión de TCP / IP

PARA VSE que está actualmente activo. El valor devuelto depende en la longitud

del área de retorno pasada.

Área de retorno de ocho bytes. Cuando la longitud del área de retorno aprobada

es ocho bytes, el área devuelta consta de las siguientes partes:

• Cuatro bytes que contienen los caracteres visualizables "1.5E", "1.5F" "1.5G",

"2.1x" o "2.2x", donde x es el nivel de modificación (0 a 9).

• Cuatro bytes que contienen el valor hexadecimal binario que es interno

asociado con la cadena de caracteres de cuatro bytes que la precede.

Los valores de la versión del producto que se pueden generar son los siguientes.

Formato de caracteres Formato de vinario 1.5E X'00010501' 1.5F X'00010502' 1.5G X'00010503' 2.1x X'000201xx' (see text) 2.2x X'000202xx' (see text)

35


Para la versión 2 en formato binario, xx es el nivel de modificación y los rangos

de 00 a 99, dependiendo del nivel de mantenimiento activo en el sistema.

Área de retorno de veinte bytes. Cuando la longitud del área de retorno

aprobada es 20 bytes, el área devuelta contiene lo siguiente:

• 8 bytes: versión de caracteres (vv.rr.mm) de la pila TCP / IP

• 8 bytes: versión de caracteres (vv.rr.mm) de la interfaz BSD (IPNRBSDC)

• 4 bytes: versión hexadecimal (00vvrrmm) de la pila TCP / IP

int getversion(int *,int *) rc = getversion(&p1,&p2)



satisfactoriamente. Un -1 indica que un error tiene ocurrió, y la variable errno contiene más información.

p1 Puntero al área de retorno para la versión. p2 Puntero a la longitud del área de retorno. La longitud es una

palabra completa que contiene 8 o 20.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRVERS punto.

givesocket( ) La función givesocket () hace que el socket especificado esté disponible para un

función takeocket () emitida por otro programa. Cualquier enchufe puede ser

dado. Típicamente, givesocket () es usado por un programa maestro que obtiene

enchufes mediante una llamada accept () y los entrega a la aplicación programas

que manejan un socket a la vez.

int givesocket(int,struct clientid *); rc = givesocket(socket,&clientid);

36




satisfactoriamente. Un -1 indica que un error tiene ocurrió, y la variable errno contiene más información.

socket El número de socket. clientid Puntero a una estructura clientid que especifica el programa que

es recibir el zócalo.

El procesamiento de Givesocket / takesocket se ve afectado por la opción $

OPTGTSP en $ SOCKOPT. Consulte el "Apéndice A: Fase de opciones de $

SOCKOPT" página 196, para obtener detalles sobre cómo configurar opciones en

una fase de opciones personalizadas.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRGIVE punto.

listen( ) La función listen () indica al sistema que supervise un puerto para solicitudes de

conexión de hosts remotos.

int listen(int,int); rc = listen(socket,backlog);


Variable Descripción rc El código de retorno. Un 0 indica que una condición de escucha

tiene establecido y continuará por lo solicitado Número de eventos. Un -1 indica que un error tiene ocurrió, y la variable errno contiene más información.

socket El número de socket que se asociará con la escucha. Esta el socket contiene el número de puerto que se utilizará.

clientid El número máximo de conexiones entrantes a ser puesto en cola. Consulte las Notas de uso para obtener más información.

Notas de uso:

• Esta función se usa con solicitudes TCP; no se aplica a UDP peticiones.

37


• El valor de la acumulación se anula en los siguientes casos:

1. Si QUEDMAX en $ SOCKOPT es igual a 0, se ignora la acumulación y el valor lo establece el comando PORTQUEUE.

2. Si QUEDMAX en $ SOCKOPT es mayor que 0 pero menor que el valor de la acumulación, entonces se usa el valor de QUEDMAX.

De manera predeterminada, la palabra clave QUEDMAX se establece en 0. Consulte el “Apéndice A: $ Fase de opciones de SOCKOPT ", página 196, para obtener detalles sobre la configuración de opciones en una fase de opciones personalizadas.

• Si va a utilizar el comando PORTQUEUE, debe asegúrese de que QUEDMAX = 0 en $ SOCKOPT para permitir que el comando controla la puesta en cola de las solicitudes de conexión entrantes (SYN). Ver "Puerto En cola "en el capítulo" Rendimiento "de TCP / IP PARA VSE Guía de instalación para obtener información sobre el comando PORTQUEUE.

Cuando los clientes intentan conectarse a un puerto en un estado de escucha, la solicitud puede ser rechazado La mayoría de los clientes vuelven a intentar el intento de conexión en algún momento número de veces configurado para un período de tiempo específico antes renunciando.

El comando TCP / IP DIAGNOSE CONNREJ puede usarse para diagnostica si las solicitudes de conexión entrante se rechazan. Las solicitudes rechazadas pueden ser reintentadas y seguir siendo exitosas, pero la conexión en cola se puede implementar para evitar la conexión del cliente rechazos por un servidor en un puerto específico.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRLIST punto.

receive( ), recv( ) La función de recepción () permite que su programa reciba datos enviados desde un servidor remoto. Esta función no devuelve el control hasta que los datos estén transferidos.

int receive(int,char *,int,int); result = receive(socket,&buffer,length,flags);


Variable Descripción rc Si la función se completa con éxito, este campo contiene La longitud

de los datos recibidos. Un valor de -1 indica que ha ocurrido un error, y la variable errno contiene más información.

socket El número de socket que se utilizará para la función de recepción (). clientid Señala el búfer que se utilizará para recibir los datos.

38


Variable Descripción length La longitud del búfer. flags Proporcionado por compatibilidad. Código cero como marcador de

posición.

Notas de uso:

• Si está utilizando UDP y un datagrama es demasiado grande para caber en el

área siempre que se descarten los bytes en exceso.

• Después de emitir la función de recepción (), el control no se devuelve hasta

que los datos se colocan en su búfer y están disponibles. Para comprobar la

disponibilidad, use una de las funciones select ().

• Esta función se ve afectada por la opción $ OPTXNBK en $ SOCKOPT. Consulte



Para Assembler, COBOL, otros idiomas, llame al punto de entrada IPNRRECV.

recvfrom( ) La función recvfrom () es similar a la función de recepción (), pero incluye

parámetros adicionales y se usa solo en aplicaciones UDP.

int recvfrom(int,char *,int,int,struct sockaddr *,length); result = recvfrom(socket,&buffer,len,flags,&sockaddr,s_len);


Variable Descripción result Si la función se completa con éxito, este campo contiene la longitud

de los datos recibidos. Un valor de -1 indica que ha ocurrido un error, y la variable errno contiene información adicional.

socket El número de socket que se utilizará para la función de recepción (). Buffer Señala el búfer que se utilizará para recibir los datos. Len La longitud del búfer. Flags Proporcionado por compatibilidad. Código cero como marcador de

posición. Sockaddr Apunta a una estructura sockaddr que contiene un puerto y / o

Dirección IP. s_len La longitud de la estructura sockaddr.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRREFRpunto.

39


select( ) La función select () examina un subconjunto de los sockets de su programa e

indica cuáles están listas para ser procesadas.

int select(int,fd_set *,fd_set *,fd_set *,struct timeval *); tot = select(num,&read,&write,&exc,&time);


Variable Descripción tot Una vez completada, la función devuelve el número total de

enchufes que están listos para el procesamiento. Solo enchufes marcado para examen están incluidos. Un valor de -1 indica que se ha producido un error y que la variable errno contiene más información.

num Especifica el número de socket más alto a examinar. Los números de socket de hasta 8000 son válidos, por lo que establecer un valor razonable reduce los gastos generales.

read Señala una cadena de bits que indica qué sockets deben ser examinados por los datos disponibles para la lectura. Cada 1 bit hace que se examine el zócalo correspondiente. Si el socket no tiene datos elegibles para lectura, el bit está desactivado. NULL indica que la cadena no se usa.

write Señala una cadena de bits que indica qué sockets deben ser examinados por disponibilidad para escribir. Cada 1 bit hace que se examine el zócalo correspondiente. Si el socket no está disponible para escribir, el bit está desactivado. NULL indica que la cadena no se usa.

exc Señala una cadena de bits que indica qué sockets deben ser examinados por excepciones pendientes. Cada 1 bit causa el zócalo correspondiente a examinar. Si el zócalo no tiene una excepción pendiente, el bit está desactivado. NULL indica que la cadena no se usa.

time Apunta a una estructura de tiempo que indica cuánto tiempo La función select () debe esperar. Si este valor es NULL, select () no devuelve el control hasta al menos un socket Está listo para procesar. De lo contrario, el control se devuelve cuando uno o más enchufes están listos o cuando el intervalo de tiempo caduca, lo que sea antes.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRSELE punto.

40


selectecb( ) La función selectecb () examina un subconjunto de los sockets de su programa y

determina cuáles están listos para el procesamiento. Esta función es similar a la

función select () excepto que un BCE indica que un socket está listo.

int selectecb(int,fd_set *,fd_set *,fd_set *,struct timeval *,int *); tot = selectecb(num,&read,&write,&exc,&time,&ecb);


Variable Descripción tot Al finalizar, tot contiene el número total de tomas Listo para el

procesamiento. Solo enchufes marcados para examen están incluidos. Un valor de -1 indica que un se ha producido un error y la variable errno contiene Información Adicional.

num Especifica el número de socket más alto a examinar. Los números de hasta 8000 son válidos, por lo que establecer un valor razonable El valor reduce los gastos generales.

read Señala una cadena de bits que indica qué sockets deben ser examinados para leer los datos elegibles. Cada 1 bit provoca el socket correspondiente a examinar. Si el zócalo tiene sin datos elegibles para lectura, el bit está desactivado. NULL indica que la cadena no se usa.

write Señala una cadena de bits que indica qué sockets deben ser examinados por datos elegibles para escritura. Cada 1 bit provoca el socket correspondiente a examinar. Si el zócalo tiene sin datos elegibles para escritura, el bit está desactivado. NULL indica que la cadena no se usa.


time Apunta a una estructura de tiempo que indica cuánto tiempo selectecb () puede permanecer pendiente. Si este valor es NULL, selectecb () monitorea los sockets indefinidamente o hasta que uno esté listo. De lo contrario, el BCE se publica cuando al menos un socket está listo o cuando el tiempo el intervalo caduca, lo que sea antes.

ecb Apunta a un BCE que se publica cuando al menos un socket está listo para procesar o cuando el intervalo de tiempo opcional tiene caducado.

41


Notas de uso:

• La función selectecb () siempre devuelve el control inmediatamente. Ahí está

sin espera implícita incluso cuando no hay sockets listos para procesar.

• Cuando emite selectecb (), la dirección del BCE se anota dentro de cada socket

seleccionado por las cadenas de bits. El BCE se publica cada vez que un el socket

seleccionado está listo para su procesamiento. Para determinar qué enchufes

están listos, use cualquier función select ().

• Si vuelve a emitir selectecb (), todos los sockets especificados se actualizan

para apuntar a un nuevo BCE.

• Después de asignar un BCE a un socket, no se puede quitar. Lo único la forma

de evitar esta restricción es asignar una diferente (o ficticia) BCE al zócalo.

• Si especifica un valor de tiempo y finaliza antes de que un socket esté listo, la

función pendiente selectecb () finaliza y se publica el BCE.

Para ensamblador, COBOL e idiomas similares, llame al IPNRSECB punto de

entrada.

selectex( ) La función selectex () examina un subconjunto de los sockets de su programa y

determina cuáles están listos para el procesamiento. El selectex () es similar para

seleccionar (), pero incluye un BCE que puede usarse para terminar el espera

implícita.

int selectex(int,fd_set *,fd_set *,fd_set *,struct timeval *,int *); tot = selectex(num,&read,&write,&exc,&time,&ecb);


Variable Descripción tot Una vez completada, la función selectex () devuelve el Número total

de sockets que están listos para el procesamiento. Solo se incluyen los enchufes marcados para el examen. Si una se produce un error, se devuelve un -1 y la variable errno contiene Información Adicional.

num Especifica el número de socket más alto a examinar. Los números de socket de hasta 8000 son válidos, por lo que establecer un valor razonable reduce los gastos generales.

read Señala una cadena de bits que indica qué sockets deben ser examinados para leer los datos elegibles. Cada 1 bit provoca el socket correspondiente a examinar. Si el zócalo tiene sin datos elegibles para lectura, el bit está desactivado. NULL indica que la cadena no se usa.

42


Variable Descripción write Señala una cadena de bits que indica qué sockets deben ser

examinados por datos elegibles para escritura. Cada 1 bit provoca la zócalo correspondiente a examinar. Si el zócalo no es disponible para escritura, el bit está desactivado. NULL indica que la cadena no se usa.


time Apunta a una estructura de tiempo que indica cuánto tiempo selectex () debería esperar. Si este valor es NULL, selectex () no regresa hasta que al menos un zócalo esté listo para proceso. De lo contrario, el control se devuelve cuando uno o más los sockets están listos o cuando expira el intervalo de tiempo, lo que sea antes

Ecb Apunta a un solo BCE o una lista de BCE. Usuario múltiple Los BCE están permitidos en selectex () cuando $ OPTMECB La opción está establecida en $ SOCKOPT. Ver "Apéndice A: $ Fase de opciones de SOCKOPT ", página 196, para obtener detalles sobre establecer opciones en una fase de opciones personalizadas. Además de ser terminado por un socket o tiempo listo vencimiento del intervalo, selectex () también regresa cuando el BCE está publicado

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRSELX punto.

send( ) La función send () transmite datos a un host remoto.

int send(int,char *,int,int); bytes_sent = send(socket,&msg,length,flags);


Variable Descripción bytes_sent Si la llamada es exitosa, el número de bytes enviados. Un valor de -

1 indica que se ha producido un error y que el La variable errno contiene información adicional.

socket El número de socket que se utilizará para la transmisión. msg Apunta a un búfer que contiene los datos a transmitir.

43


Variable Descripción length La longitud de los datos a transmitir. flags Proporcionado por compatibilidad. Código 0 como marcador de

posición.

Por defecto, los datos se envían sin esperar un acuse de recibo para desempeño

mejorado. Esto se puede anular eliminando el Configuración de la opción $

OPTSNWT en $ SOCKOPT. Ver "Apéndice A: $ Fase de opciones de SOCKOPT ",

página 196, para obtener detalles sobre cómo configurar opciones en un fase de

opciones personalizadas.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRSEND punto.

sendto( ) Las aplicaciones UDP pueden usar la función sendto () para enviar datos a un

servidor remoto. Es similar a la función send () pero tiene dos funciones

adicionales parámetros.

int sendto(int,char *,int,int,struct sockaddr *,length); bytes_sent = sendto(socket,&buffer,len,flags,&sockaddr,ad_len);


Variable Descripción bytes_sent Si la llamada es exitosa, este es el número de bytes enviados. Un

valor de -1 indica que se ha producido un error y que La variable errno contiene información adicional.

socket El número de socket que se utilizará para la transmisión. buffer Apunta a un búfer que contiene los datos a transmitir. len La longitud de los datos a transmitir. flags Proporcionado con fines de compatibilidad. Código cero como un

marcador de posición. sockaddr Apunta a una estructura sockaddr que contiene un puerto y / o

Dirección IP. ad_len La longitud de la estructura sockaddr.

Para Assembler, COBOL y otros idiomas, llame a la entrada IPNRSETO punto.

44


seterrs_default( ) La función seterrs_default () indica las ubicaciones predeterminadas para errno e

iprc variables.

int seterrs_default(int *,int *); rc = seterrs_default(&errno,&iprc);


Variable Descripción rc El código de retorno. Esto siempre es cero. errno Apunta a la variable entera (palabra completa) que se va a recibir

errno valores. Puede anular este valor para un determinado socket con la función seterrs_socket ().

iprc Apunta a la variable entera (palabra completa) que se va a recibir valores de iprc. Puede anular este valor para un determinado socket con la función seterrs_socket ().

Por defecto, las variables errno e iprc residen en el controlador de socket

programa, y solo hay una copia en cada partición. Si quieres tu C programa para

ser reentrante, debe proporcionar sus propias copias de estos dos variables.

Para Assembler, COBOL y otros idiomas, llame a la entrada IPNRERRD punto.

seterrs_socket( ) La función seterrs_socket () indica las ubicaciones para errno y Variables iprc que

se utilizarán para llamadas que involucren el socket especificado.

int seterrs_socket(int,int *,int *); rc = seterrs_socket(socket,&errno,&iprc);


Variable Descripción rc El código de retorno para la operación. Esto siempre es cero. socket El socket a asociar con las variables. errno Apunta a la variable entera (palabra completa) que se va a recibir

errno valores. iprc Apunta a la variable entera (palabra completa) que se va a recibir

valores de iprc.

45


Por defecto, las variables errno e iprc residen en el controlador de socket

programa, y solo hay una copia por partición. Si quieres tu C programa para ser

reentrante, debe proporcionar sus propias copias de estos dos variables Los

valores codificados con seterrs_socket () anulan los establecidos con

seterrs_default ().

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRERRS punto.

setsockopt( ) La función setsockopt () le permite establecer varios valores de opciones

Disponible en un zócalo.

int setsockopt(int,int,int,char *,int); rc = setsockopt(socket,sol_socket,option,&data,length);


Variable Descripción rc El código de retorno. Un 0 indica éxito. A -1 indica un se produjo

un error y la variable errno tiene más información. socket El número del socket a modificar. sol_socket El nivel de la llamada. Este es el único valor permitido. option La opción a configurar. Los valores válidos son los siguientes:

• SO_NONBLOCK: establece el socket actual en sin bloqueo para conecta. Cuando se emite un connect () sin esta opción, el programa de llamada se coloca en un estado de espera hasta que se complete la solicitud de conexión. Esta opción permite que connect () regrese inmediatamente al programa de llamada, que utiliza un seleccione para la cadena de bits de escritura de socket para probar completar con exito. • SO_LISTCHKC: limita el número de conexiones permitido en una toma de escucha. El número de las conexiones permitidas están determinadas por la opción parámetro de recuento de la función listen (). Si no lo hace configura esta opción, el número de conexiones es ilimitado (que es el predeterminado). • SO_REUSEADR: permite múltiples sockets con destino al mismo puerto. Por defecto, una función bind () falla si otro socket ya está vinculado al puerto especificado en la solicitud de enlace.

Data Apunta a un área que contiene datos dependientes de opciones. Esta el campo se ignora.

46


Variable Descripción length La longitud de los datos dependientes de la opción. Este campo es

ignorado.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRSETS punto.

setsysid( ) La función setsysid () se puede usar para establecer la ID del TCP / IP FOR VSE

pila con la que desea que su programa se comunique. Esto permite el programa

para anular la ID predeterminada. Consulte la sección "Conexión a TCP / IP ",

página 27, para obtener más información sobre cómo configurar la ID de la pila.

int setsysid(char); rc = setsysid(id);


Variable Descripción rc El resultado contiene la ID de pila binaria que se está utilizando. Un

valor de -1 indica que se ha producido un error y que el La variable errno contiene más información.

Id La identificación de la pila es el primer y único parámetro pasado. El valor pasado debe ser de 2 caracteres de 00 a 99. Opcionalmente, puede pasar los caracteres "GETS" a obtener la ID de pila actualmente en uso.

Para Assembler, COBOL y otros idiomas, llame a la entrada IPNRSYID punto.

shutdown( ) En TCP / IP FOR VSE, la función shutdown () funciona exactamente igual que

función close (), terminando todo el procesamiento en un socket y devolviendo

el socket al sistema.

int shutdown(int,int); rc = shutdown(socket,how);



un error, y la variable errno contiene más información. socket El número de socket a cerrar.

47


Variable Descripción how Bajo algunas implementaciones, este valor controla las funciones

de los sockets que se van a terminar. El parámetro se ignora.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRSHUT punto.

socket( ) La función socket () adquiere un socket. La sintaxis es la siguiente:

int socket(int,int,int); number = socket(domain,type,protocol);


Variable Descripción number Si la llamada es exitosa, este es el número de socket obtenido. Un

valor de -1 indica que un error tiene ocurrió, y la variable errno contiene adicional información.

domain El dominio en el que se utilizará el socket. Esto debe ser codificado como "AF_INET".

type El tipo de socket a obtener. Los tipos admitidos son SOCK_STREAM para la transmisión TCP SOCK_DGRAM para la transmisión UDP

protocol El protocolo de transmisión a utilizar. Soportado los protocolos son IPPROTO_TCP para TCP confiable IPPROTO_UDP para UDP no confiable

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRSOCK punto.

48


takesocket( ) La función takesocket () adquiere un socket de otro programa. Normalmente, el

otro programa pasa su ID de cliente y descriptor de socket y / o ID de proceso a

su programa a través del inicio de su programa lista de parámetros.

int takesocket(struct clientid *,int); rc = takesocket(&clientid,socket);



un error, y la variable errno contiene más información clientid Apunta a la estructura clientid que identifica el aplicación de la que

está tomando un socket. socket El número de socket.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRTAKE punto.

49


Funciones de Almacenamiento

Esta sección describe las funciones de utilidad que proporcionan subrutinas para

Manipulaciones variables y de bits. El punto de entrada para Assembler y otros

se enumeran idiomas de alto nivel para cada función.

bcopy( ) La función bcopy () copia una variable en otra.

void bcopy(const void *,void *,int); bcopy(&source,&target,length);


Variable Descripción source Apunta a la variable fuente target Apunta a la variable objetivo length La longitud entera tanto del origen como del destino.

Notas de uso:

• La copia se realiza con MVCL. Las variables grandes se copian eficientemente.

• Se copia todo el almacenamiento variable, no solo la parte ocupada de cadenas

de caracteres.

• La longitud especificada no puede exceder la longitud de la fuente o la variable

objetivo. Si lo hace, las superposiciones de almacenamiento y las fallas aleatorias

pueden ocurrir.

Para Assembler, COBOL y otros idiomas, llame a la entrada IPNRBCOP punto.

bzero( ) La función bzero () borra el almacenamiento especificado y lo llena con binario

ceros No se devuelve ningún valor.

void bzero(void *,int); bzero(&store,length);


Variable Descripción store Apunta a la variable a rellenar con ceros length La longitud del área a despejar

50


La longitud especificada no puede exceder la longitud variable. Si lo hace, una

más grande el área de almacenamiento está despejada.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRBZER punto.

htonl( ) La función htonl () traduce un entero largo (cuatro bytes) del orden de bytes

interno de la computadora en orden de bytes de red. Porque estos son idénticos,

la función se ejecuta como una declaración de asignación simple.

unsigned long htonl(unsigned long); target = htonl(source);

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRNILF punto.

htons( ) La función htons () traduce un número entero corto de la computadora orden de

bytes interno en orden de bytes de red. Porque estos son idénticos, la función se

ejecuta como una simple declaración de asignación.

unsigned short htons(unsigned short); target = htons(source);

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRBZER punto.

inet_addr( ) La función inet_addr () convierte una IP decimal con puntos imprimible (red)

dirección a su equivalente binario.

unsigned long inet_addr(char *); addr = inet_addr(&string);


Variable Descripción addr La dirección de red devuelta. Un valor de -1 indica que la cadena

de origen no se pudo convertir. string Apunta a una cadena delimitada por cero que contiene la dirección

para ser convertido.

La cadena de origen consta de uno a cuatro enteros separados por puntos. El

valor binario resultante es de cuatro bytes de longitud.

51


Los enteros se asignan a los bytes individuales como se explica en la siguiente

tabla:

Enteros Bytes

Cuatro enteros Cada entero se asigna a un byte en el final cuerda.

Tres enteros Los dos enteros más a la izquierda se asignan a un byte cada. El entero final se almacena en dos bytes como un Valor de 16 bits.

Dos enteros El entero izquierdo se almacena como un byte. El segundo entero se almacena en tres bytes como un valor de 24 bits.

Un entero El valor se almacena como un único valor de 32 bits.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRINAD punto.

inet_lnaof( ) La función inet_lnaof () examina una dirección binaria de IP (red) y devuelve solo

la parte del host.

unsigned long inet_lnaof(struct in_addr); host = inet_lnaof(ipaddr);


Variable Descripción host El número de host ipaddr Una dirección de red binaria.

Para ensamblador, COBOL y otros idiomas, llame a la entrada IPNRINLN punto.

52


C Definiciones

Archivo de definiciones Los programas en C deben incluir el archivo socket.h. Este archivo

contiene todos los definiciones de funciones, parámetros, variables y

estructuras necesarias para creando una aplicación de socket en

lenguaje C. Estas definiciones incluyen el abordar las estructuras

descritas en esta sección. Consulte el archivo socket.h para El conjunto

completo de definiciones.

Address Tag Struct La variable sockaddr asigna una etiqueta de dirección para un socket.

Una etiqueta de dirección le permite colocar información en un socket o

recuperar datos existentes información de un zócalo. Esta estructura es

la siguiente.

struct sockaddr unsigned short sa_family; /* Set to AF_INET for IPv4 */ /* or AF_INET6 for IPv6 */ char sa_data[14]; /* Address data */

IPv4 Address Struct Para mayor comodidad, la estructura de la dirección del socket IPv4 se

reasigna por sockaddr_in con granularidad adicional. Esta estructura es

la siguiente:

struct sockaddr_in /* IPv4 socket address structure */ short sin_family; /* Always set to AF_INET */ unsigned short sin_port; /* Port number */ unsigned long sin_addr; /* Network (IP) address */ char sin_zero[8]; /* Pad, binary zeros */

Client ID Struct La siguiente estructura clientid se puede utilizar para identificar una

aplicación.

struct clientid int domain(4) char jobnmae(8) char taskname(8) char type(1) char taskid(1) unsigned short partitionid(2) int token(4)

53


Macros Las siguientes instrucciones macro están incluidas en el archivo C socket.h. Estas

macros proporcionan compatibilidad con otras implementaciones y pueden

simplificar las operaciones de codificación complejas.

FD_SET Esta macro activa un solo bit en una cadena. Se usa junto con la función select ().

FD_SET(n,p *)


Variable Descripción n El número de bit basado en uno p Señala una cadena de bits

FD_CLR Esta macro apaga un solo bit en una cadena. Se usa junto con la función select ().

FD_CLR(n,p *)



FD_ISSET Esta macro prueba un solo bit en una cadena y determina su estado. Un valor de

1 (verdadero) se genera si el bit está activado.

FD_ISSET(n,p *)



54


FD_COPY Esta macro copia una cadena de bits.

FD_COPY(f *,t *)


Variable Descripción f Apunta a la cadena fuente t Apunta a la cadena objetivo, que debe tener la misma longitud

como la cadena de origen

FD_ZERO Esta macro llena una cadena de bits completa con ceros binarios.

FD_ZERO(p *)


Variable Descripción p Señala una cadena de bits

55


Assembler Definitions

Estructuras de direcciones Las siguientes estructuras de direcciones se pueden usar para desarrollar

Assembler programas de socket:

* * * sockaddr_in IPv4 socket address structure USOCKIN DSECT UFAMILY DS H UPORT DS H UIPADDR DS F * * * sockaddr_in6 IPv6 socket address structure U6SOCKIN DSECT U6LENGTH DS XL1 Length of this structure U6FAMILY DS XL1 Protocl family U6PORT DS XL2 UDP or TCP port number U6FLOW DS XL4 IPv6 flow info(not used) U6IPV4AD EQU U6FLOW IPv4 address(32-bits) U6IPV6AD DS XL16 IPv6 address(128-bits) U6SCOPE DS XL4 Scoped interfaces(not used) U6L EQU *-U6LENGTH Length of this area AF_INET EQU 2 Protocol family for IPv4 AF_INET6 EQU 19 Protocol family for IPv6 SOCK_STREAM DC F'1' TCP stream socket SOCK_DGRAM DC F'2' UDP datagram socket * * For assembler programs, the errno is returned in: ENTRY IPERRNO IPERRNO DS F * * For assembler programs, the iprc is returned in R15 and: ENTRY IPRETCD IPRETCD DS F

Programas de muestra Hay ejemplos de programas de servidor y cliente disponibles para mostrar cómo el socket Las funciones se pueden llamar desde un programa de lenguaje Assembler. El código fuente de estos programas está en el archivo SAMPBSDC.ZIP, que puede descargarlo de CSI International en www.csi-international.com.

Estos programas se describen a continuación.

Servidor El programa de servidor de ejemplo BSDSERVR en SAMPBSDC.ZIP realiza las siguientes tareas:

• Inicializa y adjunta tres subtareas VSE.

• Invoca la llamada a la función socket () para crear un socket.

• Invoca la función bind () al puerto 6045 para el socket creado.

• Invoca la función listen () para esperar una solicitud de un cliente aplicación llamada BSDCLINT.

56




• Distribuye una de las sub tareas de VSE adjuntas para procesar el comando y

envía una respuesta a la aplicación cliente que envió el comando.

Cliente El programa cliente de ejemplo BSDCLINT en SAMPBSDC.ZIP realiza las siguientes

tareas:

• Invoca la llamada a la función socket () para crear un socket.

• Invoca la función connect () al BSDSERVR.

• Lee un comando de SYSIPT.

• Invoca la función send () para enviar un comando a BSDSERVR.

• Invoca la función de recepción () para recibir una respuesta de BSDSERVR.

• Invoca la función close () para cerrar la conexión.

57


Manejo de errores

Códigos de retorno y Error Las variables iprc y errno registran el estado de finalización del funciones Números la variable iprc contiene el código de retorno y errno contiene El código del número de error (razón). Para la mayoría de las funciones, un código de retorno (iprc) de 0 indica que se completó con éxito y -1 indica que la solicitud falló. Para solicitudes fallidas, el número de error (errno) se puede examinar para Determinar la causa de la falla. Numero erroneo Si una función de socket regresa con un código de retorno de -1, el Descripciones número de error en La variable errno indica por qué falló la función. La siguiente tabla enumera los números de error, el ensamblador asociado equivale y su descripciones.

Errno errno Equate Mensaje

100 EINTERNAL /* error interno */

113 EBADF /* Parámetro no valido */

118 EFAULT /* dirección incorrecta o buffer N/A */

121 EINVAL /* parámetro invalido */

122 EIO /* Socket cerrado */

127 ENFILE /* las tablas de archivos del sistema está llena */

129 ENOENT /* No hay socket */

132 ENOMEM /* no hay memoria suficiente */

134 ENOSYS /* función no implementada */

158 EMVSPARM /* parámetro malo */

183 EVSE /* No es compatible con VSE */

1102 EWOULDBLOCK /* la solicitud podría block */

1103 EINPROGRESS /* conexión de Socket en proceso */

1104 EALREADY /* solicitud de conexión previa incompleta */

1106 EDESTADDRREQ /* Socket aún no está vinculado a un local */

1109 ENOPROTOOPT /* ninguna opción reconocida */

1112 EOPNOTSUPP /* llamada de Socket no admitida */

1114 EAFNOSUPPORT /* Address family not support */

1115 EADDRINUSE /* direccion o Puerto en uso */

1117 ENETDOWN /* Ipnet cerrado */

1121 ECONNRESET /* Connection reset/closed by peer */

58


Errno errno Equate Mensaje

1122 ENOBUFS /* No hay buffers disponibles */

1123 EISCONN /* Socket ya está desconectado */

1124 ENOTCONN /* Socket no conectado */

1127 ETIMEDOUT /* solicitud de conexión agotada */

1152 ECANCELED /* cancelar Socket */

Ensamblador y COBOL Para Assembler y otros lenguajes de alto nivel, los valores iprc y errno se Programas devuelven a las ubicaciones IPRETCD e IPERRNO, respectivamente. Los programas ensambladores deben incluir las siguientes definiciones de almacenamiento para reserve áreas de 4 bytes para estos puntos de entrada:

ENTRY IPRETCD IPRC DS F 4-byte area reserved for BSD return code

ENTRY IPERRNO ERRNO DS F 4-byte area reserved for BSD error number

Si estas referencias externas son EXTRN sin resolver en el enlace de edición,

entonces el código de retorno y el número de error no están disponibles para la

aplicación. Su aplicación puede usar seterrs_default () y el funciones

seterrs_socket () para establecer dinámicamente las direcciones para el retorno

código (iprc) y número de error (errno).

Esto significa que hay una copia de cada variable en cada partición, y su

programa no es reentrante si los usa. Para hacer tu solicitud reentrante, aún

debe resolver IPRETCD e IPERRNO en estática programa de almacenamiento,

pero luego use seterrs_default () o el función seterrs_socket () para asignar

almacenamiento dinámico para el iprc y errno variables.

59


Depuracion de aplicaciones

Para ayudar a depurar su programa de socket o para analizar las funciones y sus

resultados, puede crear una fase de opciones de depuración ($ SOCKDBG). Tú

puede usar esta fase sin hacer modificaciones a su programa. Cuando la traza

está activa, se pueden enviar mensajes al sistema VSE consola (SYSLOG) y / o a la

impresora asignada (SYSLST) del partición en la que se ejecuta la aplicación.

Consulte el “Apéndice B: Fase de depuración de $ SOCKDBG”, página 203, para

obtener detalles sobre la habilitación de mensajes de depuración y volcados de

datos especificando opciones en una fase de depuración $ SOCKDBG

personalizada.

60

3 3. High Level Pre-Processor API

Vision General

Interfaz de programación de aplicaciones de preprocesador de CSI International (API) proporciona un método independiente del idioma para realizar TCP / IP comunicaciones de su programa de aplicación. Los siguientes pasos describe cómo usas esta instalación.

1. Escriba su programa como lo haría normalmente.

2. Inserte llamadas independientes del idioma a las rutinas externas proporcionadas por TCP / IP PARA VSE, si desea utilizar TCP / IP.

3. Pase su programa a través del preprocesador TCP / IP FOR VSE. El preprocesador reemplaza las llamadas dependientes del idioma con código apropiado para el idioma que está utilizando.

4. Si es necesario, pase su programa a través de otros preprocesadores. Estos preprocesadores pueden ser proporcionados por IBM u otros proveedores.

5. Compila tu programa.

En este capítulo mostramos trabajos de muestra que pre procesan y compilan un programa. Luego explicamos cómo usar el preprocesador y cómo configurar subir las conexiones y transmitir los datos. Finalmente, proporcionamos muestra programas codificados en COBOL y PL / 1.

Running Legacy JCL El nombre del ejecutable del preprocesador es IPNETPRE. Antes de versión 1.5F, el nombre de la fase era IPNETRAN. Si usas el Nombre de fase IPNETRAN en 1.5F y versiones posteriores, IPNETRAN simplemente carga IPNETPRE y le pasa el control. Este enfoque permite a los usuarios continúe ejecutando JCL que se escribieron antes de la versión 1.5F.

IPNETPRE utiliza opciones que IPNETRAN no necesitaba. Para asegurar que los JCL existentes se pueden usar sin modificación, puede almacenar valores de parámetros en el miembro de la biblioteca VSE IPNETPRE.L. Estos valores luego se utilizan como los valores predeterminados. Los parámetros de IPNETPRE se describen en la sección "Uso del preprocesador" en la página 65.

61

Chapter 3 High-Level Pre-processor API

Procesamiento Pre-compiler Después de codificar su programa de aplicación y pasarlo a través de TCP / IP

PARA el preprocesador VSE, a menudo debe pasar la salida del pre compilador

de CSI a través de uno o más pre compiladores proporcionados por IBM u otro

vendedores. El ejemplo en esta sección muestra una forma de hacer esto.

El siguiente JCL ejecuta el trabajo SAMPLE1, que genera el trabajo SAMPLE2. Job

SAMPLE2 coloca la salida pre compilada de TCP / IP FOR VSE preprocesador en el

miembro de la biblioteca $ PRECOMP.WORK.

* $$ JOB JNM=SAMPLE1,CLASS=4,DISP=D * $$ LST CLASS=P,DISP=D * $$ PUN CLASS=A,DISP=I // JOB SAMPLE1 // OPTION NOSYSDUMP,LOG,DECK // LIBDEF *,SEARCH=(PRD2.TCPIP) // EXEC ASSEMBLY PUNCH '* $$ JOB JNM=SAMPLE2,CLASS=A,DISP=D' PUNCH '* $$ LST CLASS=P,DISP=D' PUNCH '// JOB SAMPLE2' PUNCH '// EXEC LIBR' PUNCH 'ACCESS SUBLIB=PRD2.TCPIP' PUNCH 'CATALOG $PRECOMP.WORK REPLACE=YES' END /* // EXEC IPNETPRE,PARM='LANG=COBOL,ENV=CICS' Your Program...

... /* // OPTION DECK // EXEC ASSEMBLY PUNCH '/+' PUNCH '/*' PUNCH '/&&' PUNCH '* $$ EOJ' END /* /& * $$ EOJ

62


El siguiente ejemplo de JCL ejecuta el trabajo SAMPLE3, que ejecuta IBM

Preprocesador CICS COBOL que utiliza los contenidos del miembro de la

biblioteca $ PRECOMP.WORK como entrada. Este trabajo genera el trabajo

SAMPLE4, que reemplaza el contenido del miembro de la biblioteca de entrada $

PRECOMP.WORK con La salida del preprocesador.

* $$ JOB JNM=SAMPLE3,CLASS=4,DISP=D * $$ LST CLASS=P,DISP=D * $$ PUN CLASS=A,DISP=I // JOB SAMPLE3 // OPTION NOSYSDUMP,LOG,DECK // LIBDEF *,SEARCH=(PRD2.TCPIP) // EXEC ASSEMBLY PUNCH '* $$ JOB JNM=SAMPLE4,CLASS=A,DISP=D' PUNCH '* $$ LST CLASS=P,DISP=D' PUNCH '// JOB SAMPLE4' PUNCH '// EXEC LIBR' PUNCH 'ACCESS SUBLIB=PRD2.TCPIP' PUNCH 'CATALOG $PRECOMP.WORK REPLACE=YES' END /* // EXEC DFHECP1$,PARM='CICS' * $$ SLI MEM=$PRECOMP.WORK,S=PRD2.TCPIP /* // OPTION DECK // EXEC ASSEMBLY PUNCH '/+' PUNCH '/*' PUNCH '/&&' PUNCH '* $$ EOJ' END /* /& * $$ EOJ

Debe repetir el proceso para cada preprocesador que necesita ejecutar.

63


Compiling Your Program Una vez que se completa todo el procesamiento previo, el miembro de la

biblioteca procesada previamente es pasado a un compilador, como se muestra

en el siguiente ejemplo. En esta muestra JCL, el miembro de la biblioteca $

PRECOMP.WORK se pasa a COBOL compilador. La plataforma de objetos se edita

mediante enlaces y se cataloga a la biblioteca como FASE MUESTRA. Tenga en

cuenta que cualquier otro compilador o ensamblador de idiomas podría

invocarse en lugar de COBOL.

Nota: No use la opción "CBL DYNAM" al compilar cualquier Programa COBOL que

invocará la API.

* $$ JOB JNM=SAMPLE5,CLASS=A,DISP=D * $$ LST CLASS=P,DISP=D // JOB SAMPLE5 // LIBDEF *,SEARCH=(PRD2.TCPIP,SPLIB2.PROD) // LIBDEF PHASE,CATALOG=PRD2.TCPIP // OPTION CATAL PHASE SAMPLE,* /* // OPTION LIST,LISTX,XREF // EXEC FCOBOL * $$ SLI MEM=$PRECOMP.WORK,S=PRD2.TCPIP /* /* // EXEC LNKEDT /& * $$ EOJ

64


Usando el Pre-Processor

Esta sección explica cómo usar el preprocesador. Cubre

• Orden de ejecución cuando se utiliza un preprocesador CICS

• Parámetros del preprocesador

• Declaraciones y sintaxis previas al procesador

Orden de ejecución Siempre ejecute el preprocesador TCP / IP antes que el preprocesador CICS. El preprocesador TCP / IP FOR VSE genera sentencias EXEC CICS que son reemplazados por el preprocesador CICS.

Parámetros Cuando ejecuta el programa de pre procesamiento (IPNETPRE), puede especificar una serie de parámetros en el campo PARM del EXEC declaración, junto con un parámetro opcional DEBUG si está Encontrando cualquier problema.

Alternativamente, puede incluir estas definiciones de parámetros dentro de Miembro de la biblioteca IPNETPRE.L. Puede usar el comando CATALOG para haga esto, como se muestra en el siguiente ejemplo:

CATALOG IPNETPRE.L REP=Y EOD=/+ DEBUG=OFF CC=ON /+

Los parámetros de IPNETPRE se describen en la siguiente tabla.

Parámetro Descripción

CC= [ON|OFF]

CC = ON fuerza un formato de salida de 81 bytes con el primer byte que contiene espacios en blanco. IPNETPRE está diseñado para dar salida a la tarjeta imágenes Si IJSYSPH se resigna a un tipo de dispositivo que no es UR, usa la longitud adecuada para ese tipo de dispositivo (80 bytes sin prefijo para no CC y 81 bytes para CC). Algunos productos OEM, sin embargo, puede evitar el ajuste automático de longitud. La configuración CC = ON le permite corregir este problema. Utilizar este ajuste solo si es necesario. El valor predeterminado es OFF.

DEBUG= [ON|OFF]

DEBUG = ON le dice a la API que genere una gran cantidad de mensajes de diagnóstico cuando su aplicación (no IPNETPRE) es corriendo. Ayuda a depurar problemas de aplicaciones con llamadas TCP / IP. Para deshabilitar estos mensajes, debe volver a compilar su código con DEPURACIÓN = DESACTIVADO. El valor predeterminado es OFF.

65


Parámetro Descripción

END-EXEC= [YES|NO]

END-EXEC = NO anula el requisito predeterminado para finalizar cada Declaración de "comando de protocolo EXEC" con un "END-EXEC" línea. Los operandos de comando están en líneas separadas. Cuando el pre compilador llega a una cadena que no es un operando válido, se supone El EXEC ha llegado al final. Este parámetro proporciona compatibilidad con cómo procesa IBM la llamada EXEC. El valor predeterminado es SÍ. Consulte "Terminación de línea" página 79, para información relacionada. Nota: Cuando END-EXEC = NO, cualquier operando no válido en su código indica que EXEC ha finalizado. Esto puede conducir a errores de sintaxis.

ENV=env ENV establece el entorno en el que el programa terminado debe ejecutar. Los valores válidos para env son los siguientes:

BATCH El programa se ejecuta en modo por lotes.

CICS El programa se ejecutará bajo CICS

LANG=lang LANG establece el idioma que se procesará. Valores válidos para lang son como sigue:

COBOL Para COBOL de nivel F, COBOL II, COBOL para VSE

PL1 Para PL / I

ASSEMBLER Para ensamblador F o ensamblador de alto nivel

Nota: Aunque los programas Assembler pueden usar este preprocesador, Recomendamos utilizar la interfaz macro SOCKET para mejorar controles dentro de un entorno de ensamblador.

QUIET QUIET especifica que solo se emiten mensajes importantes. Esta El parámetro no está establecido en un valor.

TRACE= [ON|OFF]

TRACE = ON permite que se realice una llamada "EXEC CICS TRACE" generado dentro de las llamadas TCP / IP. Si un "protocolo EXEC TRACE (value) "se inserta en el código de la aplicación, luego Se utiliza el valor en el código fuente. El uso de este parámetro proporciona un valor cuando ninguno ya está configurado en el código fuente. El valor predeterminado es APAGADO.

UPPER UPPER especifica que toda la salida está en mayúscula en lugar de caso mixto. Este parámetro no está establecido en un valor.

66


Pre-Procesador de códigos Los códigos de retorno de IPNETPRE se describen en la siguiente tabla. de retorno

Return Code

Descripción

0 No se encontraron errores en la entrada. IPNETPRE traducido sus llamadas EXEC al código nativo del idioma especificado por el parámetro LANG. El siguiente paso es que compiles su programa

12 Se detectó uno de los siguientes errores: • LANG está configurado en un idioma no compatible. • ENV está configurado en un entorno no compatible.

16 Se detectaron uno o más errores en su entrada. Para encontrar los errores, revise el contenido del archivo perforado producido por IPNETPRE.

24 IPNETPRE no pudo cargar su archivo de mensaje. Tú probablemente no tenga PRD2.TCPIP o PRD1.BASE en la cadena de búsqueda para la partición que ejecuta IPNETPRE.

Pre-Processor Los códigos de retorno de IPNETPRE se describen en la siguiente tabla. Statement

• Una etiqueta de identificación que especifica el protocolo de la llamada.

• Un verbo de comando que identifica la operación TCP / IP a realizar.

• Operandos opcionales específicos del verbo de comando elegido. Cada El

operando se coloca en una línea separada.

• Una etiqueta de cierre que indica el final de la declaración. Esta etiqueta puede

Incluye un terminador opcional. Consulte "Terminación de línea", página 79,

para más información.

El siguiente formato se usa para COBOL, PL / 1 y Assembler:

EXEC id verb

operand1

operand2

END-EXEC[terminator]

67


Etiqueta identificativa La etiqueta de identificación (id) en la instrucción EXEC identifica el TCP / IP

llama al preprocesador y debe ser un valor de protocolo válido. El preprocesador

examina cada declaración "EXEC id" y la reemplaza con código dependiente del

idioma que realiza las funciones especificadas. Los valores válidos para id se

describen en la tabla a continuación.

Valor id Descripción

TCP EXEC TCP se conecta y se comunica utilizando el TCP interfaz. Esto permite que una conexión TCP sea establecido en modo cliente o servidor, y permite un Secuencia de datos TCP que se transferirá ao desde programa de aplicación.

FTP EXEC FTP se conecta a FTP. Un administrador de clientes FTP es cargado en la partición TCP / IP FOR VSE para manejar el Sesión FTP Una vez que finaliza la solicitud abierta, el programa de aplicación envía comandos FTP y recibe respuestas a esos comandos a través de la conexión. Esto permite que el programa de aplicación manipule un Sesión de cliente FTP desde un programa.

CLIENT EXEC CLIENTE se conecta con el cliente de uso general gerente. Este administrador de clientes, dentro del TCP / IP FOR Partición VSE, controla la función de una serie de protocolos independientes Por ejemplo, LPR puede ser manipulado desde el programa de aplicación utilizando el gerente de cliente general al que se accede mediante este tipo de servicio.

UDP EXEC UDP se conecta y se comunica utilizando UDP interfaz. Esto permite que una conexión UDP sea establecido en modo cliente o servidor, y permite un flujo de datos UDP "sin conexión" para transferir o del programa de aplicación.

TELNET EXEC TELNET se comunica utilizando TELNET interfaz y protocolo. TELNET no es solo TCP con Traducción agregada, pero también es un protocolo. Esto permite un Conexión tipo TCP que se establecerá en un cliente o modo de servidor, y permite que un flujo de datos TCP sea transferido hacia o desde el programa de aplicación. Porque es TELNET, también verifica ciertos bits de apretón de manos y puede deshabilitar la traducción si el otro extremo lo requiere.

CONTROL EXEC CONTROL se comunica con la pila cliente de control interno y se utiliza para solicitar DNS información, ejecutar comandos TCP y más. No es un protocolo verdadero porque no envía un datagrama fuera del sistema de la pila. Este protocolo no es lo mismo que el comando "EXEC protocol CONTROL".

68


Verbos de comandos Los verbos de comandos que puede usar se resumen en la siguiente tabla.

Valor verb Descripción

CONTROL Controla la ejecución del pre compilador. No genera código como lo hacen otros comandos. Establece opciones internas para IPNETPRE.

ABRIR Abre una conexion

CERRAR Completa el procesamiento y cierra una conexión.

ENVIAR Envía datos

RECIBIR Recibe datos

ABORT Aborta la conexión

STATUS Obtiene el estado de una conexión específica

Cada uno de estos verbos y sus operandos se describen a continuación

secciones. Muchos de los verbos usan un operando llamado RESULTAREA, que se

describe a continuación.

RESULTAREA El operando RESULTAREA es utilizado por varios verbos de comando y define el

campo de trabajo de 56 bytes utilizado por el programa de aplicación. La

siguiente tabla muestra la estructura RESULTAREA. Ver los ejemplos de

programación al final de este capítulo para más información sobre cómo

codificar estos campos en COBOL.

Field nombre Field Longitud Field Descripción ECB Palabra completa Un BCE que se publica cuando en la

operación está completa

Puerto local Media palabra El número de puerto local asignado por el sistema

Puerto extranjero Media palabra El número de puerto extranjero

Direccion extranjera

Palabra completa La dirección IP (red) del servidor remoto

Bytes devueltos El número de bytes colocados en el buffer de entrada

Flags Byte Configuración de bandera interna

Codigos de retorno

Byte El código de retorno de la operación.

Terminal 40 bytes Información de terminal LU

69


Cuando utiliza RESULTAREA en sus programas, debe especificar las definiciones

de palabra completa, media palabra y dirección correctamente. El seguimiento

La tabla muestra cómo hacer esto en COBOL, PL / 1 y Ensamblador. Ver los

ejemplos de programación al final del capítulo para referencia.

Tipo de campo COBOL PL/1 Ensamblador Palabra complete IMAGEN X (4) FIXED BIN(31) DS F

Media palabra IMAGEN 9(4) COMP

FIXED BIN(15) DS H

Dirreccion NOMBRE DE DATOS

VARIABLE DS XLnn

Verbo CONTROL El verbo CONTROL le permite especificar opciones que controlan operación del

pre compilador. La sintaxis es la siguiente:

CONTROL DOUBLE [TRACE(YES|NO)]

Los operandos se describen en la siguiente tabla:

Operando Descripción

DOUBLE Dirige al preprocesador para generar literales usando comillas dobles (""). El valor predeterminado es usar comillas simples.

TRACE([YES|NO]) SÍ dirige al preprocesador para generar CICS rastrear entradas de tabla. El valor predeterminado es NO.

Los códigos de retorno se describen en la siguiente tabla:

Código de retorno

Descripción

0 No hay problemas de sintaxis.

4 Se detectó un error de sintaxis.

Verbo OPEN El verbo OPEN le permite abrir una conexión. Puedes especificar un Dirección IP

completa o solo un puerto. Los operandos le permiten activamente conectarse

con un host remoto o establecer una conexión de escucha pasiva que espera a

que el host remoto inicie la conexión.

OPEN y los otros comandos no obedecen el parámetro "CICS" si codifícalo. Este

parámetro está completamente controlado por IPNETPRE y no es incluido en la

lista de sub parámetros a continuación.

70


La sintaxis del verbo ABRIR es la siguiente:

OPEN FOREIGNPORT(halfword for assembler,

or any number for COBOL or PL/1) FOREIGNIP(4-byte character) LOCALPORT(halfword for assembler,

or any number for COBOL or PL/1) RESULTAREA(field name) DESCRIPTOR(fullword) [ACTIVE|PASSIVE] TIMEOUT(fullword for assembler,

or any number for COBOL or PL/1) [WAIT(YES|NO)] ERROR(label) SYSID(2-byte character field)

Observe la frase "o cualquier número para COBOL o PL / 1". El valor ingresado

hace que se genere un "campo MOVE value TO", por lo que longitud del área de

espera, o incluso el uso de un número real en sí, es No es un problema para

COBOL o PL / 1. Para Assembler, sin embargo, el "MVC" es usado En ese caso, las

constantes = F'value 'o = H'value' pueden ser utilizado, o debería ser un campo

con la característica exacta anotada en el declaración de sintaxis anterior. Por

ejemplo, una media palabra se usa para mover una media palabra, y una palabra

completa se usa para mover una palabra completa.


Operando Descripción FOREIGNPORT (halfword)

Identifica el número del puerto externo TCP / IP PARA VSE es conectarse o transmitir a. Se usa con el Operando ACTIVO para especificar el puerto externo para conectar con. Es un operando requerido y no hay un valor predeterminado.

FOREIGNIP (4-byte char)

Use con el operando ACTIVE para especificar la red dirección del host remoto al que conectarse. Este es un byte de 4 campos de caracteres, no un campo numérico. Use con el operando PASIVO para especificar una red dirección que puede conectarse con esta aplicación. En pasivo modo, la dirección puede ser una dirección IP específica o una dirección IP genérica Para codificar una dirección IP genérica, especifique un cero en cualquiera de los octetos que componen la dirección. Por ejemplo, especifique una dirección IP extranjera de 192.168.1.0 (X'C0A80100 ') para permitir cualquier dirección en 192.168.1 subred para conectarse a la aplicación.

71



LOCALPORT (halfword)

Especifica el número de puerto que se utilizará en el extremo local. Si no especificado o si se establece en cero, el sistema le asigna un puerto del grupo disponible. Generalmente, si estás escribiendo una aplicación de servidor TCP (lo que significa que está utilizando PASIVO), debe especificar el puerto local para que el host extranjero sabe a qué puerto conectarse. Si se está conectando a otro host (lo que significa que usted están utilizando el modo ACTIVO), el puerto local generalmente es de sin consecuencia

FOREIGNIP (4-byte char)

Especifica un área estructurada de 56 bytes en su programa que es para contener los resultados de varias operaciones EXEC TCP. La estructura se muestra anteriormente en este capítulo. Utilizar el nombre del campo, no un puntero a un campo.

DESCRIPTOR (fullword)

Identifica el hilo de la operación. Este campo debe apuntar a una palabra completa en almacenamiento donde el valor del descriptor puede ser almacenado, y este descriptor debe pasarse a todos los sockets posteriores requieren la conexión abierta. En otra palabras, una vez que se ha establecido una conexión, cualquier se puede hacer un número de llamadas de socket independientes a ese conexión, pero todos deben usar el campo descriptor para hacer referencia a la conexión abierta.

[ACTIVE| PASSIVE]

ACTIVO (predeterminado). Activo e inmediato establece una conexión a un host remoto. Un cliente la aplicación generalmente comienza con una apertura activa y intenta conectarse a una aplicación de servidor específica que es escucha pasiva (esperando que los clientes se conecten a ella). La dirección IP y el número de puerto del cliente se envían a aplicación de servidor durante el procesamiento abierto activo. El servidor puede transmitir datos al cliente ya que tiene la dirección IP y número de puerto del cliente. PASIVO. Escucha una conexión entrante. Un pasivo open puede usar un socket externo completamente especificado (FOREIGNIP (n.n.n.n) y FOREIGNPORT (0)) para esperar para que se conecte un cliente específico o un no especificado zócalo externo (FOREIGNIP (0) y FOREIGNPORT (0)) esperar cualquier conexión de cliente. Una aplicación de servidor normalmente comienza con una apertura pasiva en un número de puerto pre asignado y espera a que los clientes conectar a él. La excepción a esto es UDP, que es "Sin conexión", y así el OPEN completa inmediatamente. El usuario en ese punto debe poner en cola un RECIBIR solicitud. Para conectarse a esta aplicación de servidor, el cliente debe conocer la dirección IP y el puerto del servidor número. Este operando es el opuesto del ACTIVO operando

72



TIMEOUT (fullword)

Específica el tiempo permitido para una operación ABIERTA activa completar. Si la operación no se completa dentro de esta vez, el control vuelve a su programa. El valor es el número de intervalos de 300 segundos. 18000, para ejemplo, especifica un minuto. Para determinar el valor de un tiempo de espera de 2 minutos, use este cálculo: 2 minutos x 60 x 300 = 36000 Para una PASIVA abierta, el parámetro de tiempo de espera especifica el cantidad máxima de tiempo que se le da al host extranjero completar la conexión una vez que una solicitud SYNC es recibido. Un valor de 0 significa que nunca se agota en esta circunstancia.

WAIT([YES| NO])

Indica si el control se devolverá a su programa antes de que se complete la operación solicitada. Especifique SÍ (predeterminado) para devolver el control solo cuando La operación está completa. Especifique NO para devolver el control como tan pronto como la operación esté programada. Si especifica NO, debes esperar en el XOAECB tú mismo.

CICS Indica que el programa es una aplicación CICS.

ERROR(label) Especifica una ubicación de sucursal. Si ocurre un error, un la rama inmediata se lleva a la etiqueta especificada.

SYSID(nn) Especifica el identificador del sistema TCP / IP FOR VSE del sistema que realiza la solicitud. El valor predeterminado es 00. Debe especifique un valor SYSID si su instalación se está ejecutando TCP / IP con un identificador del sistema distinto de 00. El valor debe estar en un campo de caracteres de 2 bytes. Codificándolo como un numérico puede resultar en una falla de conexión (use = X'00 ' en lugar de 00 en Assembler, por ejemplo).

Para obtener información sobre el código de retorno, consulte “Comprobación de errores” en la página 81.

Verbo CLOSE El verbo CERRAR completa el procesamiento y cierra un existente conexión. Cerrar una conexión pretende ser una operación elegante: Los SEND pendientes continúan transmitiéndose hasta que se envían todos los datos. Es aceptable emitir varios ENVIOS seguidos de un CIERRE y esperar Todos los datos que se enviarán al destino. El usuario puede cerrar la conexión en cualquier momento. Porque cerrar una conexión requiere comunicación con el enchufe externo, las conexiones pueden permanecer en el estado de cierre por poco tiempo.

Un CIERRE ya no requiere una condición de ESPERA, por lo que ninguno es generado. Debido a que CLOSE siempre genera un buen código de retorno, no El campo ERROR es obligatorio. Si bien puede codificar esos parámetros, son ignorado y no se enumeran en la tabla a continuación.

73


No debe generar su propia ESPERA dentro de su aplicación o su el programa

permanecerá en estado de espera. El valor SYSID se establece mediante el

comando ABRIR, por lo que sí está codificado, también se ignora. La sintaxis es

como sigue:

CLOSE DESCRIPTOR(fullword) RESULTAREA(field name)


Parametro Significado


Identifica el hilo de la operación. Este campo debe apunte a una palabra completa en el almacenamiento donde el descriptor el valor de una llamada ABIERTA emitida anteriormente era almacenado.

RESULTAREA (field name)

Específica un área estructurada de 56 bytes en su programa para contener los resultados de varios EXEC TCP operaciones La estructura se muestra anteriormente en este capítulo.

Para obtener información sobre el código de retorno, consulte “Comprobación

de errores” en la página 81.

Verbo SEND El verbo ENVIAR transmite datos. Cuando emite este comando, el dato

contenido en el búfer de usuario indicado se envía. El BCE de la RESULTAREA se

publica cuando el búfer de datos es aceptado por el TCP / IP dividir. Debido a

que el valor SYSID se establece en tiempo ABIERTO e IPNETPRE controla el

proceso "CICS (valor)", esos parámetros, mientras aceptado, se ignoran y no se

enumeran en la tabla a continuación. La sintaxis es como sigue:

SEND FROM(string-address) LENGTH(fullword) RESULTAREA(field name) DESCRIPTOR(fullword) [WAIT(YES|NO)] ERROR(label)


Operando Descripción FROM (string-address)

Especifica la dirección de un búfer que contiene los datos a transmitir. Use el operando LONGITUD para indicar la cantidad de datos en el búfer.

74


Operando Descripción LENGTH (fullword)

Le dice a TCP / IP FOR VSE cuántos datos enviar a lo largo de la conexión. Este es un requisito parámetro. No hay defecto.

RESULTAREA (address)

Especifica un área estructurada de 56 bytes en su programa para contener los resultados de varios EXEC Operaciones TCP. La estructura se muestra anteriormente en Este capítulo.


Identifica el hilo de la operación. Este campo debe apunte a una palabra completa en el almacenamiento donde el descriptor el valor de una llamada ABIERTA emitida anteriormente era almacenado.

WAIT([YES|NO]) Indica si el control se devolverá a su programa antes de la operación solicitada completar. Especifique SÍ para devolver solo el control cuando se completa la operación. Especifique NO a control de retorno tan pronto como la operación es programado Si especifica NO, debe esperar el XOAECB a ti mismo.




Verbo RECEIVE El verbo RECIBIR recibe datos a través de una conexión abierta a un control

remoto anfitrión. Dependiendo de la longitud de su búfer, puede recibir una

completa o transmisión parcial Es posible que deba emitir múltiples consecutivos

RECIBE para obtener una transmisión completa. La sintaxis es la siguiente:

RECEIVE TO(field name) LENGTH(fullword) RESULTAREA(address) DESCRIPTOR(fullword) TIMEOUT(fullword) [WAIT(YES|NO)] ERROR(label)

Los operandos se describen en la tabla a continuación.

75


Operando Descripción TO(field name) Especifica el búfer para recibir datos enviados desde

servidor remoto. Utilice el operando LONGITUD para indicar la longitud del área. Cuando un RECIBIR operación completa, la longitud de datos en realidad recibido está contenido en RESULTAREA. Esta Es un operando requerido. No hay defecto.

LENGTH (fullword)

Le dice a TCP / IP FOR VSE cuántos datos desea recibir en esta solicitud. Cuando un RECIBIR operación completa, la longitud de la recibida los datos están contenidos en RESULTAREA. Si lo haces no tiene suficientes datos en cola para su aplicación para llenar el búfer, TCP / IP FOR VSE regresa cualquier dato disponible y ajusta la longitud en la RESULTAREA. Precaución: si su LONGITUD es mayor que su buffer, corre el riesgo de superponer el almacenamiento que no destruirás en tu programa.


Identifica el hilo de la operación. Este campo debe apunte a una palabra completa en el almacenamiento donde el descriptor el valor se puede almacenar y este descriptor debe ser pasado a todas las llamadas de socket posteriores para la abierta conexión. En otras palabras, una vez que una conexión tiene establecido, cualquier número de independientes se pueden hacer llamadas de socket a la conexión, pero todas de ellos deben usar el campo descriptor para hacer referencia la conexión abierta.

TIMEOUT (fullword)

Especifica el tiempo permitido para RECIBIR operación para completar. Una vez que se supera este tiempo, el control vuelve a su programa. El valor es el número de unidades de 300 segundos. 18000, para ejemplo, especifica un minuto. Para determinar el valor para un tiempo de espera de 2 minutos, use este cálculo: 2 minutes x 60 x 300 = 36000 El valor predeterminado es esperar para siempre que RECEIVE completar.



76




Especifica un área estructurada de 56 bytes en su programa para contener los resultados de varias operaciones TCP EXEC.

Verbo ABORT El verbo ABORT cierra una conexión existente. A diferencia del CIERRE sin

embargo, es similar a llevar un hacha a una línea de comunicación. Puede haber

un retraso en la eliminación del SOCKET, y la sesión, desde el punto de vista del

otro lado, fue interrumpido y puede entrar en Algún tipo de recuperación.

Cuando no puedes terminar una conexión con gracia, entonces esta es la manera

de hacerlo. Si emite un ABORT, entonces usted no puede emitir un CLOSE

porque la conexión ya no existe. Un el monitor interno intenta limpiar las sobras

que resultan de matar el sesión. La sintaxis es la siguiente:

ABORT DESCRIPTOR(fullword) RESULTAREA(field name) [WAIT(YES|NO)] ERROR(label)


Parametro Significado DESCRIPTOR (fullword)

Identifica el hilo de la operación. Este campo debe apunte a una palabra completa en el almacenamiento donde el descriptor el valor de una llamada ABIERTA emitida anteriormente era almacenado

RESULTAREA (field name)

Especifica un área estructurada de 56 bytes en su programa para contener los resultados de varios EXEC Operaciones TCP. La estructura se muestra anteriormente en Este capítulo.





77


Verbo STATUS El verbo ESTADO dirige a la API a emitir una llamada ESTADO SOCKET contra un

enchufe existente. Devuelve el CCBLOK al búfer indicado para la revisión del

programa de aplicación. Esto no se hace para verificar si una llamada SOCKET

está completa o no; eso se puede hacer marcando El BCE. Más bien, se usa para

recopilar detalles del bloque de control que serían útil, como después de emitir

un OPEN con un número de puerto local de cero, lo que significa que la pila le

asignará un número de puerto.

Esto le permite obtener el número de puerto asignado antes de que haya

conexión. La mayoría de los programas rara vez necesitan esto. Pero si tu

programa lo hace, recuerde que la información devuelta es un bloque de control

sin procesar. Debes asignarlo de nuevo al diseño definido en STATBLOK. Una

macro que viene con el producto Debe producir este diseño si es necesario.

La sintaxis de STATUS es la siguiente:

STATUS TO(field name) LENGTH(halfword) RESULTAREA(address) DESCRIPTOR(fullword) WAIT(YES) ERROR(label)


Operando Descripción TO(field name) Especifica el búfer para recibir datos enviados desde

servidor remoto. Use el operando LONGITUD para indicar la longitud del área. Cuando una operación de ESTADO completa, la longitud de los datos recibidos es contenido en la RESULTAREA. Este es un requisito operando.

LENGTH (halfword)

Le dice a TCP / IP FOR VSE cuántos datos desea recibir en esta solicitud. Cuando una operación de ESTADO completa, la longitud de los datos realmente recibidos es contenido en la RESULTAREA. Si no tienes suficientes datos en cola para su aplicación para llenar el buffer, TCP / IP FOR VSE devuelve los datos que sean disponible y ajusta la longitud en el RESULTAREA. Precaución: si su LONGITUD es mayor que su buffer, corre el riesgo de superponer el almacenamiento en el programa que no tienes la intención de destruir.

78




Especifica el búfer para recibir datos enviados desde servidor remoto. Use el operando LONGITUD para indicar la longitud del área. Cuando una operación de ESTADO completa, la longitud de los datos recibidos es contenido en la RESULTAREA. Este es un requisito operando.

WAIT(YES) Indica si el control se devolverá a su programa antes de que se complete la operación solicitada. Especificar SÍ devuelve el control solo cuando el La operación está completa. Porque esto es solo un movimiento en memoria, siempre codifique SÍ.

ERROR(label) Especifica una ubicación de sucursal. Si ocurre un error, un la rama inmediata se lleva a la etiqueta especificada. El único tipo de error sería si el CCBLOK no existe, lo que significaría que el SOCKET no existe.


Especifica un área estructurada de 56 bytes en su programa para contener los resultados de varios EXEC TCP Operaciones La estructura se muestra anteriormente en este capítulo.



Terminación de línea Las líneas de código COBOL y PL / 1 generadas pueden requerir la terminación

con signo de puntuación apropiado. Este terminador se conoce como punto final

o un terminador de alcance implícito. Termina las condiciones en curso. El

terminador COBOL es un punto (.); el terminador PL / 1 es un punto y coma (;).

Especificación de un terminador después de END-EXEC (solo) en preprocesador

declaraciones hace que esa puntuación se agregue a las generadas

declaraciones. Por ejemplo, si END-EXEC se sigue con un punto, entonces todas

las declaraciones generadas, con la excepción de una continuación declaración,

finalizará con un punto. Si un terminador válido (un período o un falta el punto y

coma), entonces no se genera puntuación.

79


El siguiente ejemplo muestra el efecto de usar "END-EXEC". (con un período) en

las declaraciones COBOL generadas.

MOVE 'Y' TO XOWAIT. MOVE 'N' TO CICS. ...other code

IF XOCODE > 0 THEN GO TO ERROR-AREA.

Nota 1: Si END-EXEC = NO en la lista de parámetros de IPNETPRE, entonces el

preprocesador verifica cada operando en el "comando de protocolo EXEC"

declaración para un terminador. Si el último operando termina con un

terminador, entonces esa puntuación final se agrega a las declaraciones

generadas. El terminador debe usarse solo en el último operando. Si se usa en

otro operando, entonces el preprocesador finaliza la instrucción EXEC en ese

punto. El siguiente ejemplo muestra cómo se especifica un período como un

terminador en una declaración previa al procesador cuando END-EXEC = NO.

EXEC TCP OPEN FOREIGNPORT(0000) LOCALPORT(LOCAL_PORT) RESULTAREA(RESULTS) SYSID('00') DESCRIPTOR(MYDESC) PASSIVE(YES) WAIT(YES). ...other code

Nota 2: Si un "EXEC TCP" (por ejemplo) forma parte de un condicional (IF),

agregar una puntuación final terminaría el IF y posiblemente cambie la lógica de

la declaración. En el siguiente preprocesador ejemplo, no se especifica un

terminador después de END-EXEC para evitar agregando puntuación al código

generado.

IF SOMETHING = "Y" THEN EXEC TCP operand1

operand2

END-EXEC ELSE CALL SOMETHING-ELSE.

80


Comprobación de errores

Bloque de control XOBLOK Si bien no queremos que ocurran errores en nuestro procesamiento TCP / IP,

puede, por supuesto, llegar un momento en que su programa tenga un

problema. Quizás la pila TCP / IP está inactiva, el servidor DNS está inactivo o

algunos Se produce otro problema. Es importante tener un sistema centralizado.

Rutina de informe de ERROR en su programa que informa el problema y le

proporciona información útil antes de recuperar o finalizar.

En el caso de un programa PL / 1 o COBOL, un bloque de control XOBLOK es

insertado en su código automáticamente cuando lo ejecuta IPNETPRE. Los

programas ensambladores deben tener una macro XOBLOK en algún lugar del

programa para generar este bloque de control. El uso de DSECT = YES convierte

este valor en un DSECT que puede asignar a un área de almacenamiento,

mientras que DSECT = NO codifica este bloque de control dentro del programa

almacenamiento.

El XOBLOK se inicializa en tiempo ABIERTO, y cada llamada de verbo TCP / IP (por

ejemplo, ABRIR o ENVIAR) hace que pequeñas partes de este bloque de control

se establecerá antes de que el bloque se devuelva a la API. La API, a su vez,

establece varios campos en XOBLOK antes de devolver el control a programa de

aplicación. Si se produce un error, los valores en ciertos XOBLOK Los campos son

importantes. Estos campos se describen en la tabla a continuación.

XOBLOK Field

Descripción

XOAPIV1 Un campo de caracteres de 8 bytes que contiene la versión / lanzamiento de IPNETPRE que generó el código.

XOAPIV2 Un campo de caracteres de 8 bytes que contiene la versión / lanzamiento de la API que intentó reparar el código.

XOCALLID Una media palabra numérica que indica qué EXEC dentro su programa causó el problema. Por ejemplo, si tu tenía un EXEC TCP CONTROL seguido de un EXEC TCP OPEN, y el problema estaba en el EXEC TCP SEND (el tercer EXEC), luego XOCALLID contendría X'0003 '.

XOREG1 Operación en campo. Este valor identifica dónde falla ocurrió para que los códigos se puedan interpretar correctamente. Los valores pares se asignan si una operación No se pudo programar. Se asignan valores impares si la operación completado con errores.

81


XOBLOK Field

Descripción

XOCODE / XORCODE

Campo de código de retorno. Por conveniencia, dos campos son proporcionado: XOCODE es un campo de media palabra, y XORCODE es un campo de un byte. Incluso para valores XOREG1 (2–12), el valor de XOCODE significa lo mismo que el código de retorno de macro SOCKET en registro 15. (Este valor no está en el registro 15.) Para impar Valores XOREG1, el valor de XOCODE está en SRCODE.

XOREG0 Campo de código de razón. Este valor puede aclarar el significado del valor XOCODE. Para algunos valores XOCODE, XOREG0 contiene el código de retorno de IBM si el fallo ocurrió durante una llamada de IBM, como GETMAIN. Incluso para valores XOREG1, el XOCODE, XOREG0 las combinaciones de códigos tienen los mismos significados que el registrar 15, registrar 0 códigos. (Vea la siguiente sección para información sobre cómo buscar estos códigos).

El contenido de estos campos debe ponerse a disposición del usuario para que

los problemas puedan ser depurados. Los primeros tres campos pueden ser

necesarios para los CSI grupo de soporte técnico si no puede resolver el

problema. Los campos XOREG1, XOCODE, XOREG0 se pueden usar para

identificar el error.

XOBLOK Field

Descripción

2 SOCKET ABIERTO programado

3 SOCKET ABIERTO completado

4 ENVIAR SOCKET programado

5 ENVIAR SOCKET completado

6 RECIBIR SOCKET programado

7 RECIBIR SOCKET completado

8 SOCKET DE ESTADO programado

9 SOCKET DE ESTADO completado

10 ABORT SOCKET programado

11 ABORT SOCKET completado

12 CERRAR SOCKET programado

13 CERRAR SOCKET completado

14 Error de validación de XOBLOK

82


Determinación de Error Use el código XOREG1 y la siguiente tabla para interpretar los códigos en

XOCODE y XOREG0. Busque los valores de esos campos en el tabla indicada para

determinar el error. Las tablas enumeradas están en el capítulo 1, "API del

ensamblador SOCKET".

Si XOREG1 contiene ...

entonces XOCODE contiene ...

y XOREG0 contiene ...

Busca el error en esta tabla:

2, 4, 6, 8, 10, o 12

un registro 15 valor un registro 0 valor

Reg15,Reg0 Codes (page 9)

3, 5, 7, 9, 11, o 13

un SRCODE valor SRCODE Field (page 11)

14, ver tabla abajo.

Si XOREG1 = 14, use la tabla a continuación para interpretar el valor XOCODE.

XOBLOK Field

Descripción

3 "EXEC CICS WAIT" inició un tiempo de espera.

16 El campo XODESC es nulo para cualquier operación excepto un ABIERTO, o NO es nulo cuando se realiza una llamada ABIERTA.

20 XOBLOK NO es nulo para una llamada ABIERTA. Esto puede indicar que el campo XOBLOK ya se está utilizando para Otra conexión.

24 El contenido de XOCOMMND no es válido. XOCOMMND se usa para pasar comandos como OPEN y CERRAR a la API.

28 El contenido de XOACCESS no es válido. XOACCESS es se utiliza para pasar el protocolo especificado (TCP o UDP) a API.

83


Conexiones y transmisiones de datos

Debe abrir una conexión antes de poder comunicarse. Conexiones puede ser activo o pasivo. Una conexión activa busca el socio especificado y negocia activamente la conexión. Un pasivo la conexión no realiza ninguna acción por sí sola, sino que espera recibir una solicitud de negociación desde el extremo remoto.

Conexión activa En el siguiente ejemplo, se le pide a TCP / IP FOR VSE que establezca un conexión Ejemplo con un sistema externo cuya dirección IP se mantiene en palabra completa IPADDRESS y cuyo número de puerto extranjero es 2000. La palabra completa SOCKDESC se debe pasar a todas las llamadas TCP EXEC posteriores para esto conexión una vez que se ha establecido. Esta es la única llamada necesaria para establecer una conexión completa con el sistema extranjero. Una vez que la RECB (contenido en el área de resultados) se publica, la conexión está lista para enviar y recibir actividad.

Una solicitud de conexión activa debe completarse dentro de un período de tiempo de espera. Debido a que se omite la especificación TIMEOUT =, el valor de tiempo de espera el valor predeterminado es dos minutos. Si la conexión no se completa dentro de dos minutos, la RECB se publica y se establece una condición de error en el RCODE campo.

05 IPADDRESS. 10 IPAD1 PICTURE X. 10 IPAD2 PICTURE X. 10 IPAD3 PICTURE X. 10 IPAD4 PICTURE X. 05 HALFWORD PICTURE 9(4) COMP. 05 HALFWORD-X REDEFINES HALFWORD. 10 BYTE1 PICTURE X. 10 BYTE2 PICTURE X. 05 RESULTS. 10 RECB PICTURE X(4). 10 RLOPORT PICTURE 9(4) COMP. 10 RFOPORT PICTURE 9(4) COMP. 10 RFOIP PICTURE X(4). 10 RCOUNT PICTURE 9(4) COMP. 10 RFLAGS PICTURE X. 10 RCODE PICTURE X. 10 RTERMTY PICTURE X(40). 05 SOCKDESC PICTURE X(4). * * Setup IPADDRESS to hold 172.20.10.10 in binary MOVE 172 TO HALFWORD. MOVE BYTE2 TO IPAD1. MOVE 20 TO HALFWORD. MOVE BYTE2 TO IPAD2. MOVE 10 TO HALFWORD. MOVE BYTE2 TO IPAD3. MOVE 10 TO HALFWORD. MOVE BYTE2 TO IPAD4. (Continúa en la página siguiente)

84


(Continúa)

* * Attempt to open a connection at 172.20.10.10 port 2000 EXEC TCP OPEN FOREIGNPORT(2000) FOREIGNIP(IPADDRESS) LOCALPORT(0) RESULTAREA(RESULTS) DESCRIPTOR(SOCKDESC) ACTIVE WAIT(YES) ERROR(BAD-OPEN) END-EXEC.

Conexión pasiva En el siguiente ejemplo, el programa de aplicación solicitó que TCP / IP PARA VSE Ejemplo escuche la llegada de una solicitud de conexión al puerto 2500. Cuando llega una solicitud de conexión, la conexión se completa y esta solicitud se publica como completo. Observe que el puerto extranjero y la dirección IP no son especificados. Esto permite que cualquier solicitud de conexión de usuario remoto sea aceptada.

* Attempt to open a passive connection * EXEC TCP OPEN FOREIGNPORT(0) FOREIGNIP(0) LOCALPORT(2500) RESULTAREA(RESULTS) DESCRIPTOR(SOCKDESC) PASSIVE ERROR(BAD-OPEN) END-EXEC.

Recibiendo información Después de establecer una conexión, el siguiente paso es recibir o enviar datos.

Esta sección muestra cómo usar EXEC TCP RECEIVE para recibir datos del

anfitrión extranjero.

En el ejemplo a continuación, EXEC TCP RECEIVE pone en cola una solicitud para

recibir información del anfitrión extranjero. Es posible que muchos reciban

solicitudes en cola en la misma conexión. Cada solicitud debe proporcionar su

propia RESULTAREA pero se refieren al mismo DESCRIPTOR. Cada solicitud se

procesa en el orden en que se pone en cola y los datos se pasan a aplicación a

medida que llega. La máxima información que se puede recibir en una solicitud

hay 65.535 bytes. Porque es inusual que 64K de datos llegar a la vez, tal

especificación desperdicia memoria.

85


La información recibida generalmente llega en piezas no mayores que tamaño de MTU del enlace. La cantidad de datos recibidos se devuelve en el Campo RCOUNT.

Es importante recordar que TCP es un protocolo orientado a la transmisión, y Se requiere iteración cuando se recibe un flujo de datos. Esto es muy diferente de la mayoría de las operaciones de E / S y solicitudes que están orientadas a registros o bloques. Una operación de E / S de disco o cinta VSE emite una solicitud de lectura, espera un BCE para indicar la finalización, verifica si hay errores y luego tiene todo el registro o bloque disponible para procesamiento. Una aplicación de flujo TCP puede enviar 4096 bytes de datos a una aplicación receptora, todo en uno recibe, o puede recibir 2000 bytes, luego 1000 bytes y luego 1096 bytes en tres recibir solicitudes por separado. TCP garantiza entregar los bytes en secuencia, pero no garantiza entregarlos en la agrupación en que fueron enviados.

Para manejar una secuencia TCP, la aplicación receptora debe hacer un bucle en la entrada transmitir hasta que se reciba la estructura de datos acordada. Un ejemplo de un la estructura de datos acordada es el protocolo telnet o FTP, en el que un retorno de carro / avance de línea en el flujo de datos indica el final de un comando o registro.

La aplicación receptora se codifica en bucle y recibe el flujo de datos. en un búfer hasta que se detecten los caracteres de retorno de carro / avance de línea en la corriente. En ese momento, la aplicación receptora sabe que ha recibido un comando o registro completo que luego puede procesarse.

El siguiente ejemplo muestra cómo recibir datos de un host externo:

05 RESULTS. 10 RECB PICTURE X(4). 10 RLOPORT PICTURE 9(4) COMP. 10 RFOPORT PICTURE 9(4) COMP. 10 RFOIP PICTURE X(4). 10 RCOUNT PICTURE 9(4) COMP. 10 RFLAGS PICTURE X. 10 RCODE PICTURE X. 10 RTERMTY PICTURE X(40). 05 SOCKDESC PICTURE X(4). 05 BUFFER. 10 WORKAREA PICTURE X(512). * * Receive a piece of data * EXEC TCP RECEIVE TO(BUFFER) LENGTH(512) RESULTAREA(RESULTS) DESCRIPTOR(SOCKDESC) WAIT(YES) ERROR(BAD-RECEIVE) END-EXEC.

86


Enviando datos El siguiente ejemplo muestra cómo transmitir datos a través de una conexión. En

este ejemplo, se envían 512 bytes de datos a través de la conexión al sistema

extranjero El RECB en RESULTAREA se publica cuando los datos son aceptados

por la partición TCP / IP, pero no significa que los datos el buffer ha llegado a la

ubicación deseada. La solicitud de envío debe hacer referencia al DESCRIPTOR

creado durante el procesamiento EXEC TCP OPEN. Las solicitudes de envío se

procesan en el orden en que se emiten. El máximo El tamaño del búfer es de

65.535 bytes. Independientemente del tamaño del búfer utilizado, cuando cada

La solicitud de envío es aceptada por la partición TCP / IP, se divide en Piezas de

diferentes tamaños para la transmisión real.

05 RESULTS. 10 RECB PICTURE X(4). 10 RLOPORT PICTURE 9(4) COMP. 10 RFOPORT PICTURE 9(4) COMP. 10 RFOIP PICTURE X(4). 10 RCOUNT PICTURE 9(4) COMP. 10 RFLAGS PICTURE X. 10 RCODE PICTURE X. 10 RTERMTY PICTURE X(40). 05 SOCKDESC PICTURE X(4). 05 BUFFER. 10 WORKAREA PICTURE X(512). * * Sends a piece of data EXEC TCP SEND FROM(BUFFER) LENGTH(512) RESULTAREA(RESULTS) DESCRIPTOR(SOCKDESC) WAIT(YES) ERROR(BAD-SEND) END-EXEC.

87


Cerrar una Conexión Una vez que haya terminado con la conexión, debe cerrarla. El seguimiento El

ejemplo muestra cómo hacer esto. Esta es una operación simple que requiere

solo el DESCRIPTOR y la RESULTAREA. Aunque el CIERRE la operación se pone en

cola detrás de cualquier operación SEND pendiente, es buena practique para

permitir solicitudes ENVIAR y RECIBIR previamente en cola para completar antes

de emitir un CIERRE.

05 RESULTS. 10 RECB PICTURE X(4). 10 RLOPORT PICTURE 9(4) COMP. 10 RFOPORT PICTURE 9(4) COMP. 10 RFOIP PICTURE X(4). 10 RCOUNT PICTURE 9(4) COMP. 10 RFLAGS PICTURE X. 10 RCODE PICTURE X. 10 RTERMTY PICTURE X(40). 05 SOCKDESC PICTURE X(4). * * Close the connection EXEC TCP CLOSE RESULTAREA(RESULTS) DESCRIPTOR(SOCKDESC) ERROR(BAD-CLOSE) END-EXEC.

Usando WAIT(NO) En algunos casos, es posible que desee usar WAIT (NO) como uno de los

parámetros en su aplicación TCP / IP FOR VSE para esperar manualmente dentro

del programa. Cuando su aplicación llama a la API, la API establece un valor en

XOAECB que apunta a un campo que contiene un puntero. En un no-CICS

aplicación, cargaría la dirección en XOAECB en un registro e invoque la macro

WAIT de IBM. Para una aplicación CICS, el campo XOAECB se puede usar como

parámetro en la ESPERA CICS normal Solicitud EXTERNA.

Los tres ejemplos a continuación muestran cómo funciona esto para cada tipo de

programa. El campo XOAECB contiene el puntero que requiere la declaración.

"NEVADA" es un campo de palabra completa que contiene un "1". Puede

insertar un '2' en NEV si elige esperar un segundo BCE. En ese caso, debe

actualizar el área a la que apunta XOAECB. El área ya contiene un BCE puntero en

la primera palabra completa, y hay espacio para incluir un segundo BCE puntero.

Los siguientes ejemplos funcionarán para lotes o CICS con la excepción de la

emisión de la ESPERA. COBOL y PL / 1 no pueden emitir una llamada WAIT

debido a cómo están diseñados para funcionar, pero en su lugar deben llamar a

un rutina de ensamblador escrita por el usuario para hacer que ESPERE por ellos.

El ejemplo de ensamblador podría ejecutarse en una partición por lotes

reemplazando el single Llamada de CICS a la emisión de la macro "WAIT" de IBM,

como se indicó anteriormente.

88


PL/1 Ejemplo El siguiente ejemplo está codificado en PL / 1:

EXEC TCP OPEN FOREIGNPORT(0000) LOCALPORT(LOCAL_PORT) RESULTAREA(RESULTS) SYSID('00') DESCRIPTOR(MYDESC) PASSIVE(YES) WAIT(NO); /* */ IF XORCODE ^= '00000000'B THEN GOTO RETPROG; EXEC CICS WAIT EXTERNAL ECBLIST(XOAECB) NUMEVENTS(NEV);

COBOL Ejemplo El siguiente ejemplo está codificado en COBOL:

EXEC TCP OPEN FOREIGNPORT(0000) LOCALPORT(LOCAL_PORT) RESULTAREA(RESULTS) SYSID(00) DESCRIPTOR(MYDESC) PASSIVE(YES) WAIT(NO). IF XORCODE > ZERO THEN GOTO RETPROG. EXEC CICS WAIT EXTERNAL ECBLIST(XOAECB) NUMEVENTS(NEV).

Nota: No use comillas alrededor del valor SYSID de dos bytes.

Ejemplos de ensamblador El siguiente ejemplo está codificado en Assembler:

EXEC TCP OPEN FOREIGNPORT(0000) LOCALPORT(LOCAL_PORT) RESULTAREA(RESULTS) SYSID('00') DESCRIPTOR(MYDESC) PASSIVE(YES) WAIT(NO) ICM R15,15,XORCODE BNZ RETPROG EXEC CICS WAIT EXTERNAL ECBLIST(XOAECB) NUMEVENTS(NEV)

La API da el mismo resultado cuando se utiliza WAIT (YES). Entonces, a menos

que tú necesita usar un segundo BCE en su ECBLIST, la codificación WAIT (YES) es

Mucho más simple.

Nota: Nunca codifique WAIT (YES) en un CLOSE. La pila controla el esperando.

89


Programas de muestra

Los siguientes programas de muestra muestran las mismas funciones en diferentes lenguajes de programación. En cada caso, tenga en cuenta las técnicas especiales utilizadas para manipular los datos.

Nota: El comando EXEC TCP se muestra en los siguientes ejemplos. Si se transfieren datos no binarios y se necesita la traducción EDCDIC-ASCII en ambas direcciones, puede usar el comando EXEC TELNET a menos que desea realizar su propia traducción en el programa. Para información sobre parámetros del comando, consulte el manual de referencia COBOL apropiado.

COBOL EXEC TCP Ejemplo

90

IDENTIFICATION DIVISION. PROGRAM-ID. SAMPLE2. AUTHOR. JOHN R. INSTALLATION. WORTHINGTON OHIO. DATE-WRITTEN. AUGUST 2, xxxx. DATE-COMPILED. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. EXEC TCP CONTROL DOUBLE(NO) END-EXEC. WORKING-STORAGE SECTION. 01 WORK-AREA-ONE. 05 PART1 PICTURE 9(4) COMP. 05 PART2 PICTURE 9(4) COMP. 05 PART3 PICTURE 9(4) COMP. 05 PART4 PICTURE 9(4) COMP. 05 IPADDRESS. 10 IPAD1 PICTURE X. 10 IPAD2 PICTURE X. 10 IPAD3 PICTURE X. 10 IPAD4 PICTURE X. 05 HALFWORD PICTURE 9(4) COMP. 05 HALFWORD-X REDEFINES HALFWORD. 10 BYTE1 PICTURE X. 10 BYTE2 PICTURE X. 05 RESULTS. 10 RECB PICTURE X(4). 10 RLOPORT PICTURE 9(4) COMP. 10 RFOPORT PICTURE 9(4) COMP. 10 RFOIP PICTURE X(4). 10 RCOUNT PICTURE 9(4) COMP. 10 RFLAGS PICTURE X. 10 RCODE PICTURE X. 10 RTERMTY PICTURE X(40). 05 MYDESC PICTURE X(4). 01 LOCAL-PORT PICTURE 9(4) COMP. 01 BUFFER. 05 WORKAREA PICTURE X(512).


PROCEDURE DIVISION. BEGIN. *---------------------------------------* * * * First Test * * * *---------------------------------------* * * Setup IPADDRESS to hold 172.20.10.10 in binary * MOVE 172 TO HALFWORD. MOVE BYTE2 TO IPAD1. MOVE 20 TO HALFWORD. MOVE BYTE2 TO IPAD2. MOVE 10 TO HALFWORD. MOVE BYTE2 TO IPAD3. MOVE 10 TO HALFWORD. MOVE BYTE2 TO IPAD4. * * Attempt to open a connection at 172.20.10.10 port 2000 * EXEC TCP OPEN FOREIGNPORT(2000) FOREIGNIP(IPADDRESS) LOCALPORT(0) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ACTIVE WAIT(YES) ERROR(SECOND-TEST) END-EXEC. DISPLAY 'Open has completed'. * * Receive a piece of data * EXEC TCP RECEIVE TO(BUFFER) LENGTH(512) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(SECOND-TEST) END-EXEC. DISPLAY 'Receive has completed'. * * Close the connection * EXEC TCP CLOSE RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ERROR(SECOND-TEST) END-EXEC. DISPLAY 'Close has completed'. *---------------------------------------* * * * Second Test * * * *---------------------------------------*

91


SECOND-TEST. * * Attempt to open a connection * MOVE 2000 TO LOCAL-PORT. EXEC TCP OPEN FOREIGNPORT(0) FOREIGNIP(0) LOCALPORT(LOCAL-PORT) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) PASSIVE WAIT(YES) ERROR(ERROR-SPOT) END-EXEC. DISPLAY 'Second Open has completed'. * * Display the foreign IP address * MOVE RFOIP TO IPADDRESS. MOVE IPAD1 TO BYTE2. MOVE HALFWORD TO PART1. MOVE IPAD2 TO BYTE2. MOVE HALFWORD TO PART2. MOVE IPAD3 TO BYTE2. MOVE HALFWORD TO PART3. MOVE IPAD4 TO BYTE2. MOVE HALFWORD TO PART4. DISPLAY PART1 '.' PART2 '.' PART3 '.' PART4 * * Receive a piece of data * EXEC TCP SEND FROM(BUFFER) LENGTH(512) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(ERROR-SPOT) END-EXEC. DISPLAY 'Second Receive has completed'. * * Close the connection * EXEC TCP CLOSE RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ERROR(ERROR-SPOT) END-EXEC. DISPLAY 'Second Close has completed'. STOP RUN. ERROR-SPOT. STOP RUN.

92


COBOL EXEC FTP

Ejemplo

IDENTIFICATION DIVISION. PROGRAM-ID. CICSFTP. AUTHOR. EBASS. DATE-COMPILED. ENVIRONMENT DIVISION. DATA DIVISION. EXEC TCP CONTROL DOUBLE(NO) TRACE(YES) END-EXEC. WORKING-STORAGE SECTION. 01 MESSAGES. 05 WTO PIC X(60). 01 SEND-AREA-ONE. 05 SUSERID PIC X(32) VALUE 'CSI'. 05 SPASSWRD PIC X(32) VALUE 'CSI'. 05 SCMD1 PIC X(8) VALUE 'QUIT'. 01 RECV-AREA-ONE. 05 RUSERID PIC X(21) VALUE 'Enter Foreign User ID'. 05 HUSERID PIC X(21) VALUE SPACES. 05 RPASSWRD PIC X(22) VALUE 'Enter Foreign Password'. 05 HPASSWRD PIC X(22) VALUE SPACES. 05 RCMD1 PIC X(30) VALUE '220 Service ready for new user'. 05 HCMD1 PIC X(30) VALUE SPACES. 05 IPADDRESS. 10 IPAD1 PICTURE X. 10 IPAD2 PICTURE X. 10 IPAD3 PICTURE X. 10 IPAD4 PICTURE X. 05 HALFWORD PICTURE 9(4) COMP. 05 HALFWORD-X REDEFINES HALFWORD. 10 IPBYTE1 PICTURE X. 10 IPBYTE2 PICTURE X. 05 RESULTS. 10 RECB PICTURE X(4). 10 RLOPORT PICTURE 9(4) COMP. 10 RFOPORT PICTURE 9(4) COMP. 10 RFOIP PICTURE X(4). 10 RCOUNT PICTURE 9(4) COMP. 10 RFLAGS PICTURE X. 10 RCODE PICTURE X. 10 RTERMTY PICTURE X(40). 05 MYDESC PICTURE X(4). 01 LOCAL-PORT PICTURE 9(4) COMP. 01 IBUFFER. 05 IP-WORKI PICTURE X(32) VALUE SPACES. 01 OBUFFER. 05 IP-WORKA PICTURE X(512) VALUE SPACES. 01 TCP-ECB2 PICTURE X(4). PROCEDURE DIVISION. MOVE 192 TO HALFWORD. MOVE IPBYTE2 TO IPAD1. MOVE 168 TO HALFWORD. MOVE IPBYTE2 TO IPAD2. MOVE 141 TO HALFWORD. MOVE IPBYTE2 TO IPAD3. MOVE 18 TO HALFWORD. MOVE IPBYTE2 TO IPAD4.

93


OPEN-FTP. MOVE 'API1 - FTP OPEN 1 ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE 6200 TO LOCAL-PORT. EXEC FTP OPEN FOREIGNPORT(21) FOREIGNIP(IPADDRESS) LOCALPORT(LOCAL-PORT) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ACTIVE WAIT(YES) ERROR(ERROR-SPOT2) END-EXEC. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RUSERID EQUAL HUSERID. PERFORM SEND-USER THRU SEND-USER-EXIT. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RPASSWRD EQUAL HPASSWRD. PERFORM SEND-SPASSWRD THRU SEND-SPASSWRD-EXIT. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RCMD1 EQUAL HCMD1. PERFORM SEND-SCMD1 THRU SEND-SCMD1-EXIT. PERFORM CLOSE-FTP. SEND-USER. MOVE 'API1 - FTP SEND SUSER ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE SUSERID TO IBUFFER. PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-USER-EXIT. SEND-SPASSWRD. MOVE 'API1 - FTP SEND SPASSWRD ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE SPASSWRD TO IBUFFER. PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-SPASSWRD-EXIT. SEND-SCMD1. MOVE 'API1 - FTP SEND SCMD1' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE SCMD1 TO IBUFFER. PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-SCMD1-EXIT. SEND-IT. EXEC FTP SEND FROM(IBUFFER) LENGTH(32) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(ERROR-SPOT2) END-EXEC. SEND-IT-EXIT.

94


RECEIVE-IT. * * I AM ONLY GUARANTEED 1 BYTE ON THIS RECEIVE * AND MAY HAVE TO DO MULTIPLE RECEIVES * IF FIXED AND WAIT(YES) IS USED, THEN I MUST WAIT * TIL THE ENTIRE BUFFER IS FILLED BEFORE BEING POSTED * MOVE 'API1 - FTP RECEIVE IT ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. EXEC FTP RECEIVE TO(OBUFFER) LENGTH(512) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(ERROR-SPOT2) END-EXEC. MOVE OBUFFER TO WTO, HUSERID, HPASSWRD, HCMD1. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. RECEIVE-IT-EXIT. CLOSE-FTP. MOVE 'API1 - FTP CLOSE 1 ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. EXEC FTP CLOSE RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ERROR(ERROR-SPOT2) END-EXEC. STOP RUN. ERROR-SPOT2. MOVE 'API1 - FTP ERROR 1 ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. STOP RUN.

95


COBOL EXEC CLIENT IDENTIFICATION DIVISION. PROGRAM-ID. CICSLPR. AUTHOR. EBASS. DATE-COMPILED. ENVIRONMENT DIVISION. DATA DIVISION. EXEC TCP CONTROL DOUBLE(NO) TRACE(YES) END-EXEC. WORKING-STORAGE SECTION. 01 MESSAGES. 05 WTO PIC X(60). 01 SEND-AREA-ONE. 05 SCMD1 PIC X(32) VALUE 'LPR'. 05 SCMD2 PIC X(32) VALUE 'SET HOST=VM'. 05 SCMD3 PIC X(32) VALUE 'SET PRINTER=LOCAL'. 05 SCMD4 PIC X(32) VALUE 'CD POWER.LST.L'. 05 SCMD5 PIC X(32) VALUE 'PRINT LPRBATCH'. 01 RECV-AREA-ONE. 05 RCMD1 PIC X(25) VALUE 'Client manager connection'. 05 HCMD1 PIC X(25) VALUE SPACES. 05 RCMD2 PIC X(10) VALUE 'LPR Ready:'. 05 HCMD2 PIC X(10) VALUE SPACES. 05 RCMD3 PIC X(10) VALUE 'LPR Ready:'. 05 HCMD3 PIC X(10) VALUE SPACES. 05 RCMD4 PIC X(10) VALUE 'LPR Ready:'. 05 HCMD4 PIC X(10) VALUE SPACES. 05 RCMD5 PIC X(10) VALUE 'LPR Ready:'. 05 HCMD5 PIC X(10) VALUE SPACES. 05 IPADDRESS. 10 IPAD1 PICTURE X. 10 IPAD2 PICTURE X. 10 IPAD3 PICTURE X. 10 IPAD4 PICTURE X. 05 HALFWORD PICTURE 9(4) COMP. 05 HALFWORD-X REDEFINES HALFWORD. 10 IPBYTE1 PICTURE X. 10 IPBYTE2 PICTURE X. 05 RESULTS.

LPR Ejemplo


MOVE 192 TO HALFWORD.

10 RECB PICTURE X(4). 10 RLOPORT PICTURE 9(4) COMP. 10 RFOPORT PICTURE 9(4) COMP. 10 RFOIP PICTURE X(4). 10 RCOUNT PICTURE 9(4) COMP. 10 RFLAGS PICTURE X. 10 RCODE PICTURE X. 10 RTERMTY PICTURE X(40). 05 MYDESC PICTURE X(4). 01 LOCAL-PORT PICTURE 9(4) COMP. 01 IBUFFER. 05 IP-WORKI PICTURE X(32) VALUE SPACES. 01 OBUFFER. 05 IP-WORKA PICTURE X(80) VALUE SPACES. 01 TCP-ECB2 PIC X(4). PROCEDURE DIVISION. MOVE 'API1 - START CICSLPR ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC.

96

MOVE IPBYTE2 TO IPAD1. MOVE 168 TO HALFWORD. MOVE IPBYTE2 TO IPAD2. MOVE 0 TO HALFWORD. MOVE IPBYTE2 TO IPAD3. MOVE 7 TO HALFWORD. MOVE IPBYTE2 TO IPAD4. OPEN-FTP. MOVE 'API1 - LPR CLIENT OPEN ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE 0 TO LOCAL-PORT. EXEC CLIENT OPEN FOREIGNPORT(0) FOREIGNIP(IPADDRESS) LOCALPORT(LOCAL-PORT) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ACTIVE WAIT(YES) ERROR(ERROR-SPOT2) END-EXEC. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RCMD1 EQUAL HCMD1. PERFORM SEND-SCMD1 THRU SEND-SCMD1-EXIT. MOVE SPACES TO WTO, HCMD2, HCMD3, HCMD4, HCMD5. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RCMD2 EQUAL HCMD2. PERFORM SEND-SCMD2 THRU SEND-SCMD2-EXIT. MOVE SPACES TO WTO, HCMD3, HCMD4, HCMD5. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RCMD3 EQUAL HCMD3. PERFORM SEND-SCMD3 THRU SEND-SCMD3-EXIT. MOVE SPACES TO WTO, HCMD4, HCMD5. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RCMD4 EQUAL HCMD4. PERFORM SEND-SCMD4 THRU SEND-SCMD4-EXIT. MOVE SPACES TO WTO, HCMD5. PERFORM RECEIVE-IT THRU RECEIVE-IT-EXIT UNTIL RCMD5 EQUAL HCMD5. PERFORM SEND-SCMD5 THRU SEND-SCMD5-EXIT. PERFORM CLOSE-CLIENT. SEND-SCMD1. MOVE 'API1 - FTP SEND SCMD1 ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE SCMD1 TO IBUFFER. PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-SCMD1-EXIT. SEND-SCMD2. MOVE 'API1 - FTP SEND SCMD2 ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE SCMD2 TO IBUFFER. PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-SCMD2-EXIT. SEND-SCMD3. MOVE 'API1 - FTP SEND SCMD3' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC.

97


MOVE SCMD3 TO IBUFFER.

PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-SCMD3-EXIT. SEND-SCMD4. MOVE 'API1 - FTP SEND SCMD4 ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE SCMD4 TO IBUFFER. PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-SCMD4-EXIT. SEND-SCMD5. MOVE 'API1 - FTP SEND SCMD5' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. MOVE SCMD5 TO IBUFFER. PERFORM SEND-IT THRU SEND-IT-EXIT. SEND-SCMD5-EXIT. SEND-IT. EXEC CLIENT SEND FROM(IBUFFER) LENGTH(32) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(ERROR-SPOT2) END-EXEC. SEND-IT-EXIT. RECEIVE-IT. * I AM ONLY GUARANTEED 1 BYTE ON THIS RECEIVE * AND MAY HAVE TO DO MULTIPLE RECEIVES * IF FIXED AND WAIT(YES) IS USED, THEN I MUST WAIT * TIL THE ENTIRE BUFFER IS FILLED BEFORE BEING POSTED MOVE 'API1 - CLIENT RECEIVE IT' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. EXEC CLIENT RECEIVE TO(OBUFFER) LENGTH(80) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(ERROR-SPOT2) END-EXEC. MOVE OBUFFER TO WTO, HCMD1,HCMD2,HCMD3,HCMD4,HCMD5. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. RECEIVE-IT-EXIT. CLOSE-CLIENT. MOVE 'API1 - CLIENT CLOSE ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. EXEC CLIENT CLOSE RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ERROR(ERROR-SPOT2) END-EXEC. STOP RUN. ERROR-SPOT2. MOVE 'API1 - CLIENT ERROR ' TO WTO. EXEC CICS WRITE OPERATOR TEXT(WTO) END-EXEC. STOP RUN.

98


PL/1 EXEC TCP Ejemplo

SAMPLE4: PROCEDURE OPTIONS(MAIN); DCL IPADDRESS BINARY FIXED(31,0); DCL MYDESC CHAR(4); DCL 1 RESULTS, 2 RECB CHAR(4), 2 RLOPORT BINARY FIXED(15,0), 2 RFOPORT BINARY FIXED(15,0), 2 RFOIP CHAR(4), 2 RCOUNT BINARY FIXED(15,0), 2 RFLAGS CHAR(1), 2 RCODE BIT(8), 2 RTERMTY CHAR(40); DCL MYDESC CHAR(4); DCL LOCAL_PORT BINARY FIXED(15,0); DCL BUFFER CHAR(512); /*---------------------------------------* * * * First Test * * * *---------------------------------------*/ /* * Attempt to open a connection at 172.20.10.10 port 2000 */ EXEC TCP OPEN FOREIGNPORT(2000) FOREIGNIP(IPADDRESS) LOCALPORT(0) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ACTIVE WAIT(YES) ERROR(SECOND_TEST) END-EXEC; /* * Receive a piece of data */ EXEC TCP RECEIVE TO(BUFFER) LENGTH(512) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(SECOND_TEST) END-EXEC; /* * Close the connection */ EXEC TCP CLOSE RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ERROR(SECOND_TEST) END-EXEC;

99


SECOND_TEST: /*---------------------------------------*

* Second Test * *---------------------------------------* * Attempt to open a connection */ LOCAL_PORT = 2000; EXEC TCP OPEN FOREIGNPORT(0) FOREIGNIP(0) LOCALPORT(LOCAL_PORT) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) PASSIVE WAIT(YES) ERROR(ERROR_SPOT) END-EXEC; /* * Display the foreign IP address */ /* Need code here..... */ /* * Receive a piece of data */ EXEC TCP SEND FROM(BUFFER) LENGTH(512) RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) WAIT(YES) ERROR(ERROR_SPOT) END-EXEC; /* * Close the connection */ EXEC TCP CLOSE RESULTAREA(RESULTS) DESCRIPTOR(MYDESC) ERROR(ERROR_SPOT) END-EXEC; RETURN; END SAMPLE4;

PL/1 Notas Para usar la interfaz TCP / IP con PL / 1 para VSE / ESA para un programa

originalmente escrito para DOS / VS PL / 1, debe tener en cuenta una importante

diferencia entre DOS / VS PL / 1 y PL / 1 para VSE / ESA. El trabajo el

almacenamiento utilizado por DOS / VSE PL / 1 generalmente se pre inicializó,

pero el almacenamiento de trabajo para PL / 1 para VSE / ESA no lo es. Para

asegurar que los programas escrito originalmente para DOS / VS PL / 1 utilizando

TCP / IP PARA VSE La API del preprocesador continúa funcionando en PL / 1 para

VSE / ESA, debe usar Las siguientes opciones en LE / VSE para estos programas:

BATCH: STORAGE(00,NONE,00,64K) CICS: STORAGE(00,NONE,00,0K)

Para obtener más información sobre este tema y estas opciones, consulte PL / I

VSE Guía de migración, IBM Manual SC26-8056-01.

100

4 4. REXX Sockets API

Visión general

Este capítulo describe la programación de aplicaciones REXX Sockets interfaz

(API). Esta interfaz es similar a las otras API en siguientes formas:

• Le permite escribir programas que interactúan con TCP / IP FOR VSE.

• Le permite utilizar los servicios TCP / IP FOR VSE para comunicarse con otras

aplicaciones TCP en la red TCP / IP.

REXX Sockets es una excelente herramienta de creación de prototipos para

codificar TCP / IP aplicaciones.

Nota: cuando se ejecuta un SOCKET OPEN, la API genera dos líneas de liberar

información sobre SYSLOG. Si quieres suprimir estas líneas, habilite UPSI-1 en esa

secuencia de trabajos. Esto es cierto solo si no estás corriendo la API SOCKET

bajo la pila TCP / IP como parte de un REXX-CGI sesión.

101

Chapter 4 REXX Sockets API

Llamadas REXX

Las llamadas que puede hacer a REXX Sockets reflejan de cerca las llamadas que

puede hacer con las interfaces de idiomas superiores discutidas en el anterior

capítulos REXX Sockets se ha mejorado con algunas extensiones REXX,

incluyendo aquellos que leen y establecen variables.

Las llamadas REXX realizan las siguientes tareas. La sintaxis de cada llamada es

descrita más adelante en este capítulo

Llamada Descripción

ABORTAR Termina inmediatamente la conexión con el extranjero anfitrión.

CERRAR Termina la conexión entre el programa REXX y la aplicación remota.

ABRIR Establece una conexión de socket con TCP / IP PARA VSE. Si un cliente emite la llamada, se conecta a un servidor. Si un el servidor emite la llamada, espera una conexión de un cliente.

RECIVIDO Acepta datos de la aplicación remota y lo hace disponible para su programa REXX.

ENVIAR Pasa datos del programa REXX al control remoto solicitud.

ESTADO Le permite verificar el estado de un TCP / IP específico conexión. Esto es útil para programas que funcionan como servidores

Variables Las llamadas REXX establecen las variables REXX que se describen a continuación

en la siguiente tabla:

Variable Descripción handle Un campo de salida que contiene un puntero especial que es

regresó de una llamada ABIERTA. Este valor se usa como un campo de entrada en llamadas posteriores. Puedes usar el mango como el nombre de entrada o puede usar un nombre diferente que contiene el valor del identificador. Puedes elegir copiar esto valor cuando emite múltiples sockets abiertos en el mismo programa.

Buffer Un campo de salida que contiene datos devueltos desde un Recibir llamada.

102


Variable Descripción errmsg Un campo de salida que contiene un mensaje de error. Si un error

se produce, REXX Sockets coloca el mensaje en esta variable en lugar de enviarlo a SYSLOG o SYSLST. Es tu responsabilidad como programador para emitir el mensaje, digamos errmsg, si hay un problema. Si ocurre un error mientras errmsg se está configurando, el mensaje se encamina a SYSLOG.

loip Un campo de salida que contiene la dirección IP local que es regresó de una llamada de ESTADO. Si necesitas saber la dirección IP local antes de establecer una conexión, usted puede usar una conexión de control. Tenga en cuenta que en un multihoming entorno, la dirección IP local que es obtenido de STATUS representa la dirección IP que es utilizado para la conexión. Si quieres la dirección IP local según lo definido por el comando SET IPADDR en TCP / IP PARA la plataforma de inicialización de VSE, debe usar el control conexión para obtenerlo.

foip Un campo de salida que contiene la dirección IP extranjera. Es creado o actualizado durante una OPEN síncrona. Si están utilizando un OPEN asincrónico y una conexión tiene establecido, luego llamadas de ESTADO posteriores actualizar foip.

loport Un campo de salida que contiene el número de puerto utilizado por sistema local TCP / IP. Tenga en cuenta que esto puede o no ser el número de puerto local que solicitó su aplicación.

foport Un campo de salida que contiene el número de puerto utilizado por sistema TCP / IP extranjero. Se crea durante un abierto síncrono. Si usa un OPEN asíncrono, es creado o actualizado por STATUS.

Connstate Un campo de salida que contiene el estado actual de la conexión. Se devuelve desde una llamada de ESTADO. Los valores contenidos en connstate tienen los siguientes significados: • Si connstate es 1, la conexión representada por el identificador es una aplicación de servidor que se encuentra en estado de escucha. En otras palabras, está esperando que alguien se conecte a él. • Si connstate es 4, se ha establecido una conexión. Las variables loip, foip, loport y foport contienen datos válidos para que su programa sepa quién se conectó a él y en qué puerto. • Si connstate no es 1 o 4, entonces el estado se considera transitorio, lo que significa que el zócalo ya no está esperando una conexión y no es Ya conectado. Si su programa va a continuar, debe cerrar y volver a abrir el socket.

103


La siguiente tabla muestra cómo las variables REXX son utilizadas por REXX

llama. Tenga en cuenta los siguientes indicadores en la tabla:

• input significa que la variable se usa como entrada para la llamada.

• salida significa que la variable se usa como salida de la llamada.

• no utilizado significa que la llamada no utiliza la variable.

Variable OPEN CLOSE SEND RECEIVE ABORT STATUS handle Salida Entrada Entrada Entrada Entrada Entrada buffer No utilizado No utilizado No utilizado Salida No utilizado No utilizado errmsg Salida Salida Salida Salida Salida Salida loip No utilizado No utilizado No utilizado No utilizado No utilizado Salida foip Salida No utilizado No utilizado No utilizado No utilizado Salida loport No utilizado No utilizado No utilizado No utilizado No utilizado Salida foport Salida No utilizado No utilizado No utilizado No utilizado Salida connstate No utilizado No utilizado No utilizado No utilizado No utilizado Salida

Códigos de Retorno Los siguientes códigos de retorno se aplican a ABRIR, CERRAR, ENVIAR, RECIBIR, y

ABORT REXX llama.

Código de retorno

Descripción

0 La llamada fue exitosa.

4 Se agotó el tiempo de espera.

8 Error no especificado. La variable errmsg contiene el Texto de error

12 La dirección IP extranjera no está disponible.

16 El sistema local TCP / IP está inactivo.

20 Versión no registrada.

104


La llamada ESTADO REXX utiliza los códigos de retorno en la siguiente tabla:

Código de retorno

Descripción

0 La llamada fue exitosa. La variable connstate contiene Información Adicional. Si connstate es 4 (lo que significa que usted tener una conexión válida), entonces las variables loip, foip, loport, y el soporte contienen información válida.

4 Llamada fallida. Esto probablemente significa que el identificador variable es no es válido.

Función de tiempo de espera Cada vez que use un socket ABIERTO para iniciar una nueva conexión, puede

configurar un valor de tiempo de espera para esa conexión. El valor del tiempo

de espera permanece vigente por la vida de la conexión. Si no establece un

tiempo de espera específico valor, se utiliza el valor predeterminado. Puedes

tener múltiples conexiones abiertas a la vez, y cada conexión utiliza el valor de

tiempo de espera establecido durante su apertura.

105


Tipo de Socket

REXX Sockets le permite codificar los tipos de socket descritos en el siguiente

tabla. Usted especifica el tipo de socket en OPEN. El auto El campo de esta tabla

indica si un socket utiliza traducción automática.

Tipo Socket Descripción Auto

CLIENTE Una conexión al cliente genérico TCP / IP FOR VSE gerente. El administrador genérico admite Ping, LPR, TRACERT, REXEC, EMAIL y DESCUBRIR clientes. por Para obtener más información, consulte "Obtención de información de red" en página 113. Para ver un ejemplo de una aplicación REXX Sockets que utiliza un conexión de cliente, ver miembro REXXPING.Z en el TCP / IP Biblioteca de distribución.

No

CONTROL Una conexión a una partición TCP / IP. Usas la conexión para obtener información de la partición. Para más información, consulte Obtención de información de red. Por un ejemplo de una aplicación REXX Sockets que usa un control conexión, ver miembro REXXCONT.Z en el TCP / IP Biblioteca de distribución.

No

FTP Una conexión a un administrador de cliente FTP TCP / IP FOR VSE. El administrador del cliente monitorea una sesión FTP bajo control de tu programa. Su programa usa ENVIAR para emitir comandos al administrador de clientes de la misma manera que usted emita comandos a un cliente FTP TCP / IP FOR VSE. El programa usa RECEIVE para obtener respuestas, que puedes analizar mirando la información devuelta en variable buffer. Su programa debe seguir el protocolo FTP estándar, lo que significa que debe saber cuándo hay datos disponibles y cuándo emitir un RECIBO. No seguir FTP El protocolo causa resultados impredecibles y generalmente negativos. Para obtener una lista de los comandos del cliente FTP, consulte TCP / IP FOR VSE Guía del usuario. Para ver un ejemplo de una aplicación REXX Sockets que utiliza un socket FTP, vea el miembro REXXFTP.Z en Biblioteca de distribución TCP / IP.

Si

TCP Una conexión a una aplicación TCP. Su programa y la aplicación TCP deben usar el mismo protocolo. Esto significa que su aplicación de socket y el socket asociado la aplicación deben acordar las especificaciones de comunicación. Por ejemplo, su aplicación debe entender cuándo tiene recibió una transmisión completa mirando los datos que recibe.

No

106


Tipo Socket Descripción Auto

TELNET Una conexión a un administrador de cliente telnet TCP / IP FOR VSE. El administrador del cliente monitorea una sesión telnet bajo control de tu programa. Este tipo de socket espera que te conectes a un demonio telnet en el extremo remoto. Después de conectarte, tú emita comandos telnet e interrogue las respuestas. TCP / IP FOR VSE siempre negocia un tipo de terminal virtual de red (NVT). Para todas las llamadas ENVIADAS, X'15 ' se agrega automáticamente al final de los datos a menos que los datos ya terminan con X'15 '. Para ver un ejemplo de una aplicación REXX Sockets que utiliza un conector telnet, consulte el miembro REXXTEL.Z en TCP / IP Biblioteca de distribución.

Si

UDP Una conexión a una aplicación UDP. Tu programa y el La aplicación UDP debe usar el mismo protocolo. Esto significa que su aplicación de socket y el socket asociado La aplicación deben acordar las especificaciones de comunicación. Por ejemplo, su aplicación debe entender cuándo tiene recibió una transmisión completa mirando los datos que recibe.

No

107


Codificación de llamadas REXX

En esta sección explicamos cómo emitir cada llamada. También mostramos la

sintaxis de cada llamada y describa los parámetros que puede usar. Los

parámetros que se muestran para cada llamada son posicionales. Esto significa

que debes use una coma para mantener el espacio si omite un parámetro.

ABRIR La llamada ABIERTA establece una conexión de socket con TCP / IP PARA VSE. La

sintaxis es la siguiente:

rc=SOCKET(type,'OPEN',loport,foip,foport,sysid,timeout,

async,mode)


Variable Descripción type Tipo de enchufe. Especifique un tipo de los "Tipos de socket"

sección en la página 106. loport Número de puerto local. Para una función de servidor, loport

especifica el número de puerto que planea escuchar. Esto es ignorado para las sesiones de CLIENTE y CONTROL.

foip Dirección IP extranjera Para una función de cliente, foip específica la dirección IP a la que planea conectarse. Para un servidor función, foip especifica una máscara. TCP / IP PARA VSE utiliza la máscara para validar la dirección IP cuando se conecta a su servidor Las reglas de validación son las mismas reglas que aplicar al parámetro IPADDR = en DEFINE FTPD y los comandos DEFINE TELNETD. Ver el TCP / IP PARA Guía de instalación de VSE para más información.

foport Dirección de puerto extranjero. Si foport está codificado, especifica el número de puerto al que planea conectarse en el extremo remoto. Si se omite foport y está codificando una función de cliente, el valor predeterminado es loport. Para una función de servidor, omita foport. Si omite foip, también debe omitir foport.

sysid ID de dos dígitos de la partición TCP / IP FOR VSE. los el valor predeterminado es 00.

timeout Tiempo permitido para que se complete la operación. El valor es el número de intervalos de 300 segundos. Si una conexión es no establecido dentro de este período, se produce un tiempo de espera. El valor predeterminado es 36000, o 2 minutos.

108


Variable Descripción async Indicador asincrónico. Especifique "N", que es el predeterminado,

para un ABIERTO síncrono. Especifique "N" si está codificando una función de servidor y quieres tu REXX programa para esperar hasta que un cliente realmente se conecte al enchufe. Especifique "N" si está codificando una función de cliente. Especifique "Y" si está codificando una función de servidor y desea control inmediatamente después de TCP / IP PARA VSE reconoce tu socket.

mode Tipo de ABIERTO. Especifique CLIENTE para emitir una apertura activa e intentar conectarse al servidor especificado por foip y foport. Especifique SERVER para emitir una apertura pasiva y esperar (sincrónicamente o asincrónicamente) a que un cliente conectate contigo.

Su programa REXX puede abrir múltiples sockets. El mango variable identifica de

forma exclusiva cada socket a TCP / IP PARA VSE. Cuando abres múltiples

sockets, debe guardar el controlador después de cada OPEN. Debes usar el

identificador correcto para cada función posterior, como ENVIAR o RECIBIR. En

los ejemplos que siguen, usamos la variable estándar nombre de la manija. Sin

embargo, puede usar un nombre de variable diferente después de Copie los

datos a ese nombre. Si no está abriendo múltiples enchufes, entonces deje que

REXX Sockets establezca el controlador y utilícelo como se muestra en los

ejemplos.

Puede especificar servidores solo para sesiones UDP, TCP y TELNET.

CERRAR La llamada CLOSE finaliza una conexión de socket con TCP / IP FOR VSE. La


rc=SOCKET(handle,'CLOSE',timeout)


Variable Descripción handle Variable de identificación devuelta de una OPEN exitosa. timeout Tiempo permitido para que se complete la operación. El valor es el

número de intervalos de 300 segundos. Si este periodo transcurre y la conexión no ha terminado, un tiempo de espera ocurre. El valor predeterminado es el valor utilizado en la llamada ABIERTA.

109


ENVIAR La llamada ENVIAR transfiere datos del programa REXX al control remoto

solicitud. La aplicación remota puede ser un socio TCP o UDP aplicación, o puede

ser una conexión de control, cliente, FTP o telnet gerente. La sintaxis es la

siguiente:

rc=SOCKET(handle,'SEND',data,timeout)


Variable Descripción handle Variable de identificación devuelta de una OPEN exitosa. data Los datos que desea enviar. timeout Tiempo permitido para que se complete la operación. El valor es el


Si SEND expira, emita una llamada de ESTADO para verificar que la conexión es

todavía válida. Si ENVIAR se completa normalmente, no necesariamente indica

que los datos fueron enviados con éxito. Simplemente significa que los datos

están en cola y será enviado por la partición TCP / IP FOR VSE.

REXX Sockets agrega automáticamente X'15 'al final de sus datos si ambos de los

siguientes son verdaderos:

1. Los datos aún no terminan con X'15 'o X'00', y

2. El tipo de conexión es CONTROL, CLIENTE, FTP o TELNET.

Se requiere el X'15 'porque los componentes enumerados esperan el comandos

para terminar en un EBCDIC CR / LF.

El valor de tiempo de espera solo es útil para TCP, UDP o TELNET conexiones

ENVIAR rc = SOCKET (manejador, 'ENVIAR', datos, timeou

110


RECIBIO La llamada RECIBIR acepta datos de la aplicación remota y realiza está disponible

para su programa REXX. La sintaxis es la siguiente:

rc=SOCKET(handle,'RECEIVE',timeout)




El búfer de salida variable contiene los datos que se reciben. Si RECIBIR agota el

tiempo de espera, el búfer se guarda con el valor nulo. El valor nulo es una

longitud de cero.

El valor de tiempo de espera solo es útil para conexiones TCP o TELNET.

ABORTAR La llamada ABORTAR termina inmediatamente la conexión con el extranjero.

anfitrión. La sintaxis es la siguiente:

rc=SOCKET(handle,'ABORT',timeout)




Tenga en cuenta las diferencias entre CLOSE y ABORT:

• Cuando emite una llamada CLOSE, TCP / IP FOR VSE cierra el conexión con

gracia. Para hacer esto, anuncia que está a punto de cerrar la conexión. El

anuncio habilita la aplicación en el otro extremo para responder

adecuadamente, lo que podría significar que se cierra abajo o que realiza el

proceso de limpieza. TCP / IP PARA VSE entonces cierra la conexión.

111


• Cuando emite una llamada ABORTAR, TCP / IP FOR VSE termina el conexión de

inmediato y luego informa a la aplicación sobre el otro termina que la conexión

está cerrada.

Use ABORT solo para las sesiones TCP o TELNET que fallan y para ninguna otra, y

solo durante condiciones donde un CIERRE es ineficaz.

STADO La llamada de ESTADO le permite verificar el estado de un TCP / IP específico

conexión. También puede usarlo para verificar que la última operación de socket

su programa realizado está completo. La sintaxis es la siguiente:

rc=SOCKET(handle,'STATUS')

La variable se describe en la siguiente tabla.

Variable Descripción handle Variable de identificación devuelta de una OPEN exitosa.

112


Obtención de información de la red

Puede realizar tres tipos de llamadas a TCP / IP FOR VSE para obtener la

red información:

Llamada Descripción

GETHOSTNAME Devuelve con el nombre de TCP / IP FOR VSE dividir. No se requieren parámetros de entrada.

GETHOSTBYNAME Traduce un nombre a una dirección IP. La fuente de la dirección IP es el dominio TCP / IP PARA VSE Nombre del cliente (si se especifica uno con el SET Comando DNS1) o el nombre de dominio interno Tabla (si se especifica una con DEFINE Comando NAME). GETHOSTBYNAME toma un parámetro: el nombre simbólico que se traducido.

GETHOSTID Devuelve con la dirección IP de TCP / IP FOR Partición VSE. Esta es la dirección IP como se define mediante el comando SET IPADDR = initialization, y no toma consideraciones de multi-homing en cuenta. Si quieres la dirección IP local que se usa actualmente para una conexión específica en un entorno multi-homing, debe emitir la llamada ESTADO DE EL SOCKET después de que la conexión es establecida.

Antes de poder usar estas llamadas, debe configurar un control de

Sockets REXX sesión con la partición TCP / IP FOR VSE.

Comenzando un Control El siguiente programa muestra cómo iniciar una conexión de control. Conexión

/* Open a control connection to the TCP/IP for VSE partition*/ rc = SOCKET('CONTROL','OPEN') if rc \= 0 then say 'rc='rc 'errmsg=' errmsg /* Send the command string. Note that for control connections, TCP/IP for VSE automatically includes X'15' at the end of the string */ rc = SOCKET(handle,'SEND','GETHOSTID') if rc \= 0 then say 'rc='rc 'errmsg=' errmsg /* Receive the response from TCP/IP for VSE */ rc = SOCKET(handle,'RECEIVE') if rc \= 0 then say 'rc='rc 'errmsg=' errmsg /* Close the control connection */ rc = SOCKET(handle,'CLOSE') if rc \= 0 then say 'rc='rc 'errmsg=' errmsg

113


Iniciando un Cliente También puede abrir una conexión con el administrador de clientes TCP / IP FOR Conexión VSE. El administrador de clientes actualmente admite Ping, LPR, TRACERT, DESCUBRE, REXEC y EMAIL clientes. Para usar estas funciones, usted debe comprender las secuencias de comandos que espera el administrador del cliente. El siguiente ejemplo muestra cómo un programa REXX usa Ping.

/* Open a client connection to the TCP/IP for VSE partition */ rc = SOCKET('CLIENT','OPEN') if rc \= 0 then say 'rc='rc 'errmsg=' errmsg /* The first interaction with the client connection must be the name of the protocol you want to use, which is either PING or LPR */ rc = SOCKET(handle,'SEND','PING') if rc \= 0 then say 'rc='rc 'errmsg=' errmsg /* Receive the response from TCP/IP for VSE. You might receive multiple lines of response so you must loop until you receive the message PING Ready:. Send each line to SYSLST in the meantime. */ Do forever rc = SOCKET(handle,'RECEIVE') if rc \= 0 then do ; say 'rc='rc 'errmsg=' errmsg ; exit if pos('PING Ready:',buffer) \= 0 then leave say buffer end /* Send a command to the Ping client */ rc = SOCKET(handle,'SEND','SET HOST=192.168.0.7') /* Receive the results. The responses to the SET HOST command are a symbolic representation of the IP address followed by the PING Ready prompt */ Do forever rc = SOCKET(handle,'RECEIVE') if rc \= 0 then do ; say 'rc='rc 'errmsg=' errmsg ; exit if pos('PING Ready:',buffer) \= 0 then leave say buffer end /* Send the Ping command to make TCP/IP for VSE really do a Ping */ rc = SOCKET(handle,'SEND','PING') /* Analyze the response. You always receive 5 lines. Each line says that the Ping was successful or that it failed. If any Ping fails, we report it. Else, we avg Ping response times and report that */ Totms = 0 Do I = 1 to 5 rc = SOCKET(handle,'RECEIVE') If pos('timeout',buffer) \=0 then, Do Say 'A ping request has timed out' Say buffer Exit End Parse var buffer 'Milliseconds:'ms Totms = totms + ms End Say 'Average Ping Response time was' totms/5 /* Close the client connection */ rc = SOCKET(handle,'CLOSE') if rc \= 0 then say 'rc='rc 'errmsg=' errmsg

Puede codificar trabajos LPR de la misma manera, pero debe asegurarse de que

las respuestas que codifica son las que recibe. Al igual que con otros

automatizados procesos en su centro de datos, las respuestas pueden cambiar

con la rutina mantenimiento.

114

5 5. Common Gateway Interfaces

Visión general

Este capítulo explica cómo programar una interfaz de puerta de enlace común, o

CGI El demonio TCP / IP FOR VSE HTTP invoca un programa CGI en respuesta a

una solicitud de un navegador web. Es responsable de devolver la siguiente

página web al navegador web. Para información sobre Para definir el demonio

HTTP, consulte la Guía de instalación de TCP / IP PARA VSE.

El navegador pasa una variedad de parámetros a través de HTTP daemon

(HTTPD) y en el CGI. El CGI realiza lo solicitado actividad y devuelve una serie de

lenguaje de marcado de hipertexto (HTML) declaraciones. Las declaraciones

HTML permiten que el navegador web muestre una atractiva pantalla de

información que puede incluir gráficos, sonidos, animación y otros elementos.

Recuerde que las páginas web usan HTML, pero no todas las páginas web usan

CGI. UNA La página web simple que muestra información estática no requiere un

CGI. La información estática es información que no cambia muy a menudo, como

Una lista de empleados dentro de su empresa. En un caso como este, el La

información se almacena una vez. Para acceder a la información, el cliente hace

clic en el nombre de una persona. Esta acción pasa una solicitud GET al web

servidor, que le dice que cargue otra página web que proporcione aún más

información. El servidor web obtiene la página web y la devuelve a El navegador

web para la visualización.

Se requiere un programa CGI cuando necesita mostrar dinámicas información. La

información dinámica es información que cambia cada hora en que se muestra

una página web. Por ejemplo, muchas páginas web muestran un contador

cuando se accede a ellos. Probablemente hayas visto una página web que dijo

algo como: "El número de personas que han accedido a esta página desde el 1 de

enero son 3.123 ". ¿Cómo funciona esto? Generalmente hay un pequeño archivo

en el servidor que contiene un número y una fecha. Cuando accedes a página

web, invoca un CGI que lee el archivo, incrementa el número, guarda el nuevo

valor e incluye esta información en la página web monitor.

115

Chapter 5 Common Gateway Interfaces

Usando CGIs con VSE

TCP / IP FOR VSE implementa un enfoque de tipo VSE para el CGI proceso. Por

ejemplo, los CGI pueden escribirse en lenguajes VSE como ensamblador y REXX.

Estos tipos de programas se cubren por separado en este capítulo. La instalación

CGI aprovecha los conceptos de VSE como multiprocesamiento y puede procesar

solicitudes rápidamente.

Los programas Assembler y REXX CGI se ejecutan bajo TCP / IP PARA VSE apilar,

en la misma partición. Si escribe un programa que puede interrumpir el pila, por

ejemplo, una que usa una macro MWAIT o realiza un trabajo pesado Funciones

de I/O, debe ejecutar el CGI externo a la pila utilizando el Utilidad CGILOAD.

Consulte "Uso de la utilidad CGILOAD" a continuación.

Si un CGI se ejecuta debajo de la pila, no emita macros como SETIME. Si necesita

emitir un "WAIT", entonces el programa debe estar escrito en ensamblador y

definido con un "TYPE = CGI-BAL". El bloque de control pasado a la rutina del

ensamblador contiene la dirección de la propia pila Rutina WAIT, que debe

utilizar en lugar de invocar el WAIT de IBM macro. Como parte de la llamada, un

puntero a la rutina interna WAIT dentro la pila se pasa para que CGI-BAL la use.

Definición de un CGI a VSE Antes de usar un CGI, debe definirlo en VSE usando DEFINE Comando CGI. La


DEFINE CGI,PUBLIC='name'[,TYPE=cgitype]

Los parámetros se describen en la siguiente tabla:

Parámetro Descripción 'name' El nombre de fase para los programas, o el nombre de PROC para

REXX cgitype Especifique CGI-BAL para un programa ensamblador (el La macro

FILEIOHD no se usa), CGI-REXX para un Programa REXX, o CGI para ensambladores CGI que usan el diseño del controlador de I/O del archivo TCP / IP FOR VSE requisitos

El programa no se carga en la partición CGI hasta que un navegador web lo

llama.

Usando el CGILOAD La utilidad CGILOAD permite que las CGI se ejecuten en una partición externa. Utilidad Eso carga el módulo CGI en el almacenamiento y abre un SOCKET a HTTPD. Cuando HTTPD necesita llamar a un CGI, primero verifica si el CGI es externo a la pila. Un CGI externo tiene prioridad, por lo que un CGI cargado en la partición externa es el que se usa. Esto te permite probar y depure un CGI antes de dejar que se ejecute debajo de la pila.

116


La sintaxis es la siguiente:

// EXEC CGILOAD,PARM='[SYSID=00|xx][,PORT=portnum]'


Parámetro Descripción xx Una ID de pila alternativa. El valor predeterminado es 00. portnum Un número de puerto específico. Esto se puede configurar si hay

un conflicto con otros servidores. Por defecto, un puerto es seleccionado automáticamente.

CGILOAD almacena un número de puerto en la partición especificada. Cuando

HTTPD escanea particiones, busca un CGILOAD en ejecución. Si se encuentra uno

HTTPD comprueba el puerto que se abrió, se conecta a él y le dice CGILOAD para

cargar y ejecutar el CGI allí. Todos los CGI se ejecutan en un solo hilo modo. Si se

están ejecutando múltiples CGILOAD y llama a un REXX CGI, HTTPD lo fuerza a un

solo hilo. No hace esto para ensamblador CGIs.

Eliminar un CGI Cuando elimina un CGI, está eliminando el módulo del almacenamiento. Tú no

están eliminando la definición CGI. La próxima vez que se invoque el programa

se carga en el almacenamiento una vez más. Esto es útil cuando quieres

actualizar un CGI. La sintaxis es la siguiente:

DELETE CGI,PUBLIC='name'

El parámetro se describe en la siguiente tabla:

Parámetro Descripción 'name' El nombre de fase para los programas ensambladores, o el

Nombre de PROC para REXX.

117


Ensamblasor CGIs

Si planea codificar un CGI de ensamblador de 31 bits, le recomendamos que

utilice La lista de parámetros documentada en esta sección. Reduce el esfuerzo

de codificación significativamente. La lista de parámetros se asigna con la macro

CGIDATA, que está contenido en PRD2.TCPIP. Se muestra el DSID CGIDATA abajo

CGIDATA DSECT , CGIID DC CL6'CGBLOK' <--- Eyecatcher CGIFPO DC H'0' <--- FPORT value CGINAME DC CL16' ' <--- Incoming user ID CGIPASS DC CL16' ' <--- Incoming password CGIILEN DC F'0' <--- Input data length CGIOLEN DC F'0' <--- Output data length CGIIPT DS AL4 <--- Input area pointer CGIOPT DS AL4 <--- Output area pointer CGIACT DC F'0' <--- Actual data area size CGIFIP DC F'0' <--- FOIP value CGILIP EQU * <--- LOIP value CGIDLENG EQU *-CGINAME <--- Length of the area

Ejemplo El siguiente programa CGI está codificado en lenguaje ensamblador de 31 bits.

* --------------------------------------------------------- * 00001000 * Program: CGIIPLD2 * 00002000 * * 00003000 * Purpose: Example of an assembler CGI program. * 00004000 * * 00005000 * Input: R2 = Pointer to control block pointer * 00006000 * Parms: See the CGIDATA control block layout * 00007000 * * 00008000 * Output: CGIOLEN indicates the returned length * 00009000 * CGIOPT points to the returned data * 00010000 * * 00011000 * CGILOAD needs to be active for this CGI to work. * 00012000 * --------------------------------------------------------- * 00013000 PUNCH ' PHASE CGIIPLD2,*' Name of the CGI 00014000 CGIIPLD2 CSECT , Start of the subroutine 00015000 USING *,RF Addressability 00016000 SAVE (14,12) Save incoming registers 00017000 LR RC,RD Copy the savearea 00018000 L RD,=A(SAVEAREA) Point to new area 00019000 ST RD,8(RC) Save backward pointer 00020000 ST RC,4(RD) Save forward pointer 00021000 LR RC,RF Get the base 00022000 DROP RF No longer needed 00023000 USING CGIIPLD2,RC New base 00024000 USING CGIPARM,R2 And map to the layout 00025000 L R2,0(R2) Point to the data 00026000 * 00027000 * If this is the first time in, display some info and setup the value. 00028000 * 00029000 CLI BODYJ,C' ' First time in ? 00030000 BNZ GETLEN No...proceed 00031000

118


GETFLD FIELD=IPLTIME Get the IPLTIME STCK value 00032000 GETIME CLOCK=YES Convert to a usable format 00033000 STCM RE,12,MMDDYY Get the month 00034000 STCM RE,3,MMDDYY+3 And the day 00035000 STCM RF,12,MMDDYY+6 And the year 00036000 ST R1,TIME Save the time 00037000 ED HHMMSS(L'HHMMSS),TIME Unpack/format the time 00038000 MVC HMS(8),HHMMSS+1 Put it in the message 00039000 MVC BODYJ(40),MSG Insert the message here... 00040000 MVC BODYNJ(40),MSG And here too 00041000 * 00042000 * Now we'll check the data passed 00043000 * 00044000 GETLEN CLC CGIILEN(4),=F'0' Is there data ? 00045000 BZ DODEF No...do the default 00046000 L R5,CGIIPT Point to the data 00047000 CLI 5(5),C'Y' Java request ? 00048000 BZ DOJAVA Yes...proceed 00049000 CLI 5(5),C'N' No Java request ? 00050000 BZ DOTEXT Yes...proceed 00051000 DODEF MVC CGIOLEN(4),DEFLEN Get the length 00052000 MVC CGIOPT(4),=AL4(DEFPAGE) Point to the data 00053000 B EXIT Return to HTTPD 00054000 * 00055000 * If JAVA=YES, then display info in Java format 00056000 * 00057000 DOJAVA MVC CGIOLEN(4),JAVALEN Get the length 00058000 MVC CGIOPT(4),=AL4(JAVA) Point to the data 00059000 B EXIT Return to HTTPD 00060000 * 00061000 * If JAVA=NO, then display info in text format 00062000 * 00063000 DOTEXT MVC CGIOLEN(4),TEXTLEN Get the length 00064000 MVC CGIOPT(4),=AL4(NOJAVA) Point to the data 00065000 * 00066000 EXIT L RD,4(RD) Regain savearea 00067000 LM RE,RC,12(RD) Regain the regs 00068000 XR RF,RF Clear the return code 00069000 BR RE Return to caller 00070000 * ---------------- Data Area -------------------- * 00071000 LTORG , 00072000 SAVEAREA DS 9D 00073000 TIME DS F HHMMSSF RETURNED HERE 00074000 HHMMSS DC XL9'2120207A20207A2020' 00075000 * 00076000 MSG DC CL20'System was IPLed on ' 00077000 MMDDYY DC CL8'MM/DD/YY' 00078000 DC CL4' at' 00079000 HMS DC CL8'HH:MM:SS' 00080000 * 00081000 DEFPAGE DC C'<HTML><HEAD><TITLE>CGIIPLD2 Test Page</TITLE>' 00082000 DC C'</HEAD><BODY><FORM ACTION="CGIIPLD2" METHOD=GET">' 00083000 DC C'<CENTER><H1>CGIIPLD2 Test Page</H1><H2><I>' 00084000 DC C'Perform one of the following tests:<HR></I>' 00085000 DC C'Cursor Selection Test<BR><BR>Pass the' 00086000 DC C'<A HREF="CGIIPLD2?JAVA=NO"><I>NOSCRIPT</I></A>' 00087000 DC C'or the <A HREF="CGIIPLD2?JAVA=YES"><I>SCRIPT' 00088000 DC C'</I></A>parameter to CGIIPLD2<HR></I><H2>' 00089000 DC C'Form SUBMIT Test<BR><I><BR>Select an option and' 00090000 DC C'press the Test button that follows:<BR></I></H2>' 00091000

119

DC C'<B><INPUT TYPE="radio" NAME="JAVA" VALUE="NO">' 00092000 DC C'NOSCRIPT<INPUT TYPE="radio" NAME="JAVA" ' 00093000 DC C'VALUE="YES"> SCRIPT</B>' 00094000 DC C'<INPUT TYPE="submit" name="SUBMIT" value="Test">' 00095000 DC C'<HR></FORM></BODY></HTML>' 00096000 DEFLEN DC AL4(*-DEFPAGE) 00097000 * 00098000 JAVA DC C'<HTML><HEAD><TITLE>CGIIPLD2 Test Page</TITLE>' 00099000 DC C'</HEAD><BODY>' 00100000 DC C'<SCRIPT LANGUAGE="JavaScript">' 00101000 DC C'',X'0D25' 00106000 DC C'</SCRIPT>' 00107000 DC C'<A HREF="../CGIIPLD2">Return to menu' 00108000 DC C'</A></BODY></HTML>' 00109000 JAVALEN DC AL4(*-JAVA) 00110000 * 00111000 NOJAVA DC C'<HTML><HEAD><TITLE>CGIIPLD2 Test Page</TITLE>' 00112000 DC C'</HEAD><BODY><H1><HR>' 00113000 BODYNJ DC CL40' ' 00114000 DC C'<HR></H1><A HREF="../CGIIPLD2">Return to menu' 00115000 DC C'</A></BODY></HTML>' 00116000 TEXTLEN DC AL4(*-NOJAVA) 00117000 * ---------------- Dummy Sections --------------------- * 00118000 CGIDATA DSECT=YES Define the parameter 00119000 IPW$EQU 00120000 END CGIIPLD2 End of program 00121000

Nota:

Tenga en cuenta que si bien la primera palabra completa de R2 contiene el

parámetro bloque, también hay una segunda palabra completa que contiene la

dirección del TCP / IP PARA VSE rutina de ESPERA interna. Si necesita emitir una

ESPERA, cargue esta segunda palabra completa en R15, señale su BCE en R1 y

BASSM en ello. Nuevamente, esto es solo si necesita emitir un WAIT.

Tenga en cuenta que esto solo se aplica al tipo CGI-BAL. El otro El formato del

ensamblador, TYPE = CGI, difiere en que sus requisitos de diseño son idénticos a

un controlador de E / S de archivo TCP / IP FOR VSE.

120


REXX CGIs

REXX es un lenguaje excelente para la creación de prototipos de aplicaciones CGI. En esto

En la sección, explicamos cómo codificar un programa REXX y mostrar un ejemplo.

Programación Su programa REXX recibe los siguientes parámetros:

• ID de usuario

• Contraseña

• Datos

• FOIP

• FOPORT

• LOIP

• LOPORT

Si la seguridad está desactivada, el ID de usuario y la contraseña están

configurados en ANÓNIMO. Después de que el programa REXX recibe los datos,

procesa y luego devuelve la página web. Para hacer esto, invocas el HTML ()

función.

Para ilustrar el poder y la simplicidad de esta interfaz, considere el siguiente programa de muestra. Este programa permite al usuario ingresar VSE consola de comandos y recibe la respuesta del navegador web. Como explicado anteriormente, recibe la identificación de usuario, contraseña, datos y otros campos. Un encabezado estándar para su programa puede aparecer de la siguiente manera:

/* Get the passed parameters */ userid=arg(1) password=arg(2) data=arg(3) foip=arg(4) /* */

En este ejemplo, no estamos interesados en el LOIP, por lo que no hay necesidad de referenciarlo. Los datos pasados al CGI son formateados por la web navegador. El navegador web pasa los parámetros en el orden en que están recibidos. Esto incluye el nombre del parámetro, precedido por un ampersand (&) y seguido de un signo igual (=), y luego los datos. Esta secuencia se repite hasta que no haya más datos. Por ejemplo, suponga que envía tres campos denominados UNO, DOS y TRES, y los campos contienen, respectivamente, las cadenas de datos 111, 222 y 333. Los datos de su programa recibe está en el siguiente formato:

&ONE=111&TWO=222&THREE=333 121


Una vez que tenga la información y la haya procesado, debe enviarla datos de

vuelta al demonio HTTP.

Para hacer esto, utiliza la función REXX HTML. Por ejemplo, para enviar para

responder una simple respuesta de "Gracias", puede usar el siguiente código:

rc=HTML('<HTML><TITLE>Response</TITLE><BODY>') rc=HTML('<H2><B><I>Thank you</B></I></H2>') rc=HTML('</BODY></HTML>')

Eso es todo lo que hay para escribir un simple CGI REXX. La cantidad de datos

puede ser grande y estar contenido en una sola llamada HTML (), o puede ser

pequeño y use varias llamadas HTML (). Menos llamadas son más rápidas, pero

no significativamente así.

Requisitos de ejecución Al igual que con un programa ensamblador, debe realizar las siguientes acciones

antes de que pueda ejecutar su CGI:

1. Catalogue su programa REXX en una biblioteca VSE que se encuentra en

LIBDEF busque la cadena para su partición TCP / IP FOR VSE CGILOAD. Esto es un

programa, no un documento, por lo que no es necesario que esté en la sub

biblioteca que contiene tus documentos HTML. Si lo pones en el HTML

sublibrary, asegúrese de que la sublibrary HTML sea parte de LIBDEF cadena de

búsqueda, como se muestra en el siguiente ejemplo:

// LIBDEF *,SEARCH=(PRD1.BASE,USR.HTML)

2. Defina un HTTPD. Si mantiene todas sus páginas web para HTTP daemon

HTTP1 en PRD2.HTML y usa un programa REXX llamado VSECOM, puede usar las

instrucciones de control en el siguiente ejemplo:

DEFINE CGI,PUBLIC='VSECOM',TYPE=CGI-REXX DEFINE HTTPD,ID=HTTP1,ROOT='PRD2.HTML',CONFINE=NO DEFINE FILE,PUBLIC='PRD2',DLBL=PRD2,TYPE=LIBRARY

Ejemplo El siguiente programa REXX funciona como una consola VSE en una web

navegador.

122


CATALOG VSECOM.PROC /*Program: VSECOM Purpose: Demonstrate how to code a sample CGI: TCP/IP for VSE. This CGI will: 1) Send a dynamic screen to the user 2) Read a passed VSE command entered by the user 3) Return data back to the Web browser Description: This program is an example of how to code a REXX-CGI. */ userid=arg(1) /* Get the passed user name */ password=arg(2) /* Get the passed password */ data=arg(3) /* Get the passed command */ foip=arg(4) /* 15-byte IP-address string */ inlen=length(data) /* Get the length passed */ if inlen=0 then do /* A null length returns this screen*/ x=HTML('text/html;') /* Required to force MIME type HTML */ x=HTML('<HTML><HEAD><TITLE>' x=HTML('VSE Console Command Processor</TITLE></HEAD>') x=HTML('<BODY TEXT="#993300" BGCOLOR="#66FF99"><CENTER>') x=HTML('<H2><B><I><FONT COLOR="#000000">') x=HTML('VSE Console Command Processor') x=HTML('</FONT></I></B></H2></CENTER><P><HR>') x=HTML('<FORM METHOD=GET ACTION="VSECOM">') x=HTML('Input:<INPUT TYPE="text" NAME="COMMAND" SIZE=25>') x=HTML('<BR><HR></BODY></HTML>') exit end parse upper var data request 9 command /* Data was passed */ ADDRESS CONSOLE /* Activate interface */ 'ACTIVATE NAME CGICONR PROFILE REXNORC' 'CART USCHI' command /* Pass command to VSE */ rc = GETMSG(msg.,'RESP','USCHI',,5) /* Get the response */ x=HTML('text/html;') /* Required to force MIME type HTML */ x=HTML('<HTML><HEAD><TITLE>') /* Pass back headings */ x=HTML('VSE Console Command Processor</TITLE></HEAD>') x=HTML('<BODY TEXT="#993300" BGCOLOR="#66FF99"><CENTER>') x=HTML('<H2><B><I><FONT COLOR="#000000">') x=HTML('VSE Console Command Processor') x=HTML('</FONT></I></B></H2></CENTER><P><HR>') x=HTML('<FORM METHOD=GET ACTION="VSECOM">') x=HTML('Input:<INPUT TYPE="text" NAME="COMMAND" SIZE=25>') x=HTML('<BR><HR>') x=HTML('<FONT COLOR="#000066"><PRE>') i = 1 /* Insert the response */ do while i <= msg.0 x=HTML(msg.i) i=i+1 end x=HTML('</BODY></HTML>') /* And the HTML footer */ ADDRESS CONSOLE 'DEACTIVATE CGICONR' /* Deactivate interface*/ Exit

123

6 6. SSL/TLS for VSE APIs

Vision general

La función SSL / TLS para VSE proporciona tres API para desarrollar aplicaciones

de socket TCP / IP criptográficamente seguras:

• API de capa de sockets seguros (página 125) Esta API le permite desarrollar

aplicaciones habilitadas para SSL / TLS en el Plataforma VSE que utiliza funciones

que se pueden invocar dentro de Assembler, C, y otros idiomas que usan

convenciones de enlace de llamada / guardado estándar.

Para obtener información sobre la compatibilidad con el protocolo TLS 1.2,

consulte el “Apéndice C: Mejora de TLS 1.2 ”en la página 208.

• API de CryptoVSE (página 148) Esta API le permite implementar algoritmos

criptográficos en un VSE solicitud.

• Interfaz de cifrado de cifrado común (página 182)

Esta API le permite controlar el algoritmo de cifrado y la clave valores utilizados

en una aplicación sin cambiar la aplicación en sí. Las funciones de esta API se

pueden invocar desde Assembler, COBOL, u otros idiomas de alto nivel que

utilizan el enlace estándar de llamada / guardar convenciones.

La función SSL / TLS para VSE se proporciona con TCP / IP FOR VSE, pero debe

activarse con una clave de producto. Consulte "SSL / TLS para VSE" capítulo en la

Guía de características opcionales de TCP / IP FOR VSE para obtener más

información. Ese capítulo también contiene una introducción a SSL / TLS

protocolo.

124

Chapter 6 SSL/TLS for VSE APIs

Secure Socket Layer (SSL) and Transport Layer Security (TLS) API

Puede usar SSL / TLS para la API de VSE para desarrollar SSL / TLS habilitado aplicaciones en la plataforma VSE. El tradicional apretón de manos SSL / TLS entre un cliente con SSL / TLS y un servidor con SSL / TLS sigue este proceso:

1. El servidor asigna un socket, se une a un puerto, realiza una escucha y emite una aceptación.

2. El cliente se conecta al servidor (por ejemplo, la aplicación VSE programa) y envía un mensaje de saludo con el nivel de versión más alto del protocolo que admite y una lista ordenada de cifrado preferido suites.

3. El servidor, que se ejecuta en VSE, pasa el control al socket seguro rutina de inicialización, que realiza el protocolo de enlace SSL / TLS real. Durante el apretón de manos, el servidor responde al saludo del cliente mensaje eligiendo el nivel de lanzamiento del protocolo y la cifrada suite que se utilizará durante la sesión. El servidor también envía su Certificado PKI X.509v3. A continuación, una función muy segura y compleja genera el material clave que se utiliza para el cifrado, descifrado y autenticación de mensajes

4. Después de que el apretón de manos se complete con éxito, la conexión está lista para intercambiar datos de forma segura utilizando el socket seguro de lectura y escritura funciones de SSL / TLS para la API de VSE.

El SSL / TLS para la API de VSE está modelado de manera similar a las funciones C de la referencia y guía de programación SSL de OS / 390 (manual de IBM número SC24-5877). Las solicitudes escritas para cumplir con estos las especificaciones se transfieren fácilmente a VSE. Las funciones descritas en él se pueden llamar las siguientes páginas desde el ensamblador y el C lenguajes de programación.

Opciones de asistencia de hardware Puede configurar varias opciones que afectan la explotación del hardware. Configuraciones Asistencias que se utilizan en muchos de los SSL / TLS y criptográficos funciones estas opciones, descritas en la tabla a continuación, se configuran utilizando valores de palabras clave en la fase de opciones $ SOCKOPT. Ver "Apéndice A: $ Fase de opciones de SOCKOPT ", página 196, para obtener detalles sobre cómo configurar opciones en un fase de opciones personalizadas.

Configuraciones de opciones

Descripción

SSLFLG2=$OPTSNHC No use criptografía de hardware para RSA operaciones Establecer esta opción suprime el uso de criptografía de hardware para RSA Cifrar las solicitudes de algoritmo. Ver también Notas abajo.

125


Configuraciones de opciones

Descripción

SSLFLG2=$OPTSNHC Nunca publique CP Assist Cryptographic Función (CPACF) z / arquitectura hardware instrucciones. Ver también las Notas a continuación.

SSLFLG2=$OPTSFZA Emita siempre CPACF z / architecture instrucciones de hardware Ver también las Notas a continuación. Tenga cuidado al elegir esta opción. Si el las instrucciones de hardware no están disponibles, un operación excepción programa-chequeo anormal ocurrirá en la aplicación.

Notas:

1. Cuando se negocia la versión TLS 1.2 del protocolo, el hardware las ayudas

para RSA y CPACF deben estar disponibles, y el Las configuraciones $ OPTSNHC, $

OPTSNZA y $ OPTSFZA se ignoran.

2. Normalmente, se detectan las instrucciones de hardware z / architecture

CPACF automáticamente y se usa cuando está disponible. El $ OPTSNZA y Las

opciones de $ OPTSFZA le permiten suprimir o forzar, respectivamente, el uso de

instrucciones criptográficas de hardware CPACF.

Códigos de error El miembro SSLVSE.A contiene explicaciones breves de la mayoría de los códigos

devuelto por las funciones SSL cuando se produce un error. Este miembro está

en el Biblioteca TCP / IP PARA VSE. Para un análisis más detallado, vea la sección

“Problemas de depuración” en la página 194.

Funciones Las funciones SSL / TLS para la API de VSE se describen a continuación páginas de

esta sección.

126


gsk_free_memory( ) Esta función se mantiene para la portabilidad de las aplicaciones OS / 390. Es no

utilizado por SSL / TLS para la API de VSE. La sintaxis es la siguiente.

#include <sslvse.h> void gsk_free_memory(void * address,

void * reserved);


Parámetro Descripción Address Puntero a la memoria que se va a liberar. La dirección fue pasada

a la aplicación por una llamada previa a un Función SSL. Reserved Reservado para uso futuro. Codifique un nulo.

Los códigos de retorno son los siguientes:

Código de retorno

Descripción

Zero Completar con éxito.

Non-zero Ocurrió un error. Consulte la sección "Depuración Problemas ”en la página 194.

Notas de uso:

• Esta función no se usa actualmente.

• Para Assembler, use macro SSLVSE para generar las áreas de datos requeridas

y llame al punto de entrada IPCRFMEM contenido en IPCRYPTS cubierta de

objetos Vea los programas de muestra SSLSERVR y SSLCLINT para

especificaciones detalladas de la interfaz del ensamblador.

• Para obtener información sobre la compatibilidad con el protocolo TLS 1.2,


127


gsk_get_cipher_info( ) Esta función solicita información relacionada con el cifrado para SSL / TLS para

VSE. La información determina el nivel de encriptación que el sistema puede

admite y devuelve una lista de especificaciones de cifrado que SSL puede usar.

Esta permite que una aplicación determine, en tiempo de ejecución, el nivel de

SSL cifrado que puede solicitar la aplicación instalada.

La sintaxis es la siguiente.

#include <sslvse.h> int gsk_get_cipher_info(int level, gsk_sec_level * sec_level, void * reserved);


Parámetro Descripción Level Determina el tipo de información de cifrado a ser devuelto Los

tipos son los siguientes: • GSK_LOW_SECURITY. Causa solo cifrado exportable información a devolver. Este valor es útil cuando configurar comunicaciones SSL con sistemas que pueden estar ubicados fuera de los EE. UU. y Canadá y en cualquier área donde las funciones criptográficas fuertes no son disponible. • GSK_HIGH_SECURITY. Causas exportables e información de cifrado nacional que se devolverá. Vea los campos v3cipher_specs y cipher_specs en la estructura gsk_soc_init_data, en la función gsk_secure_soc_init (), para obtener una lista de valores de cifrado válidos.

sec_level Puntero al área de datos gsk_sec_level. Reserved Reservado para uso futuro. Codifique un nulo.

La estructura gsk_sec_level específica información sobre el nivel de criptografía

que está disponible en el sistema. El mosto de aplicaciones asignar la memoria

necesaria para esta estructura. A su regreso exitoso, el contenido de la

estructura es conjunto. El área de datos gsk_sec_level tiene la siguiente

estructura:

typedef struct gsk_sec_level { int version; /* Output: System SSL version */ char v3cipher_specs[64]; /* Output: The sslv3 cipher specs allowed */ char v2cipher_specs[32]; /* Output: The sslv2 cipher specs allowed */ int security_level; /* Output: Initially one of */ /* GSK_SEC_LEVEL_US, */ /* GSK_SEC_LEVEL_EXPORT, */ /* GSK_SEC_LEVEL_EXPORT_FR */ } gsk_sec_level;

128


Los campos en la estructura gsk_sec_level se describen en la tabla a

continuación.

Field Descripción

versión Especifica la versión del sistema SSL que es siendo utilizado. Esto devuelve el valor GSK_VERSION3 como se define en <sslvse.h>.

v3cipher_specs[64] Especifica las especificaciones de cifrado SSL / TLS que son aceptable en el sistema. Esta información está contenida en el campo v3cipher_specs en el estructura gsk_soc_init_data que se pasa en el llamada gsk_secure_soc_init ().

v2cipher_specs[32] El SSL / TLS para la implementación de VSE no admite SSLv2, y las v2cipher_specs contienen información nula

nivel_de seguridad Especifica el nivel de cifrado que es aceptable en el sistema. Uno de los siguientes los valores, tal como se definen en <sslvse.h>, se devuelven en este campo: GSK_SEC_LEVEL_US GSK_SEC_LEVEL_EXPORT


Código de retorno

Descripción


Non-zero Ocurrió un error. Consulte la sección "Depuración Problemas ”en la página 194.

Notas de uso:

• Puede usar gsk_get_cipher_info () para determinar los valores válidos que se

especifican en cipher_specs del área gsk_soc_init_data utilizada por

gsk_secure_soc_init ().


y llame al punto de entrada IPCRGCIN contenido en IPCRYPTS cubierta de





129


gsk_get_dn_by_label( ) Esta función opcional le permite identificar el nombre del miembro que contiene

la clave privada y los certificados. La sintaxis es la siguiente:

#include <sslvse.h> char * gsk_get_dn_by_label(char * label);


Parámetro Descripción label Apunta a una cadena de caracteres terminada en nulo del

miembro de la biblioteca contenido en el llavero lib.sublib. El nombre del miembro debe tener ocho caracteres o menos en longitud y terminará con un carácter nulo (x'00 ').


Código de retorno

Descripción

Valor positivo

Completar con éxito. El valor es un puntero a una cadena de caracteres que identifica al miembro de la biblioteca nombre.

Cero o un valor negativo

Ocurrió un error. Consulte la sección "Depuración Problemas” en la página 194.

Notas de uso:

• Para Assembler, use la macro SSLVSE para generar los datos requeridos áreas y

llame al punto de entrada IPCRGDBL contenido en IPCRYPTS cubierta de objetos

Vea los programas de muestra SSLSERVR y SSLCLINT para especificaciones

detalladas de la interfaz del ensamblador.



130


gsk_initialize( ) Esta función establece el entorno general SSL / TLS para VSE para partición actual

después de que la función se complete con éxito, la aplicación está lista para

llamar a SSL / TLS para interfaces VSE y crear y Utilice conexiones de enchufe

seguras.


#include <sslvse.h> int gsk_initialize(gsk_init_data * init_data);


Parámetro Descripción init_data Puntero al área gsk_init_data

El área gsk_init_data tiene la siguiente estructura:

typedef struct gsk_init_data { char * sec_types; /* Minimum security protocol: */ char * keyring; /* Key ring file name */ char * keyring_pw; /* Key ring password */ char * keyring_stash; /* File name - stashed passwrd */ long V2_session_timeout; /* Number of seconds for SSLV2 */ long V3_session_timeout; /* Number of seconds for SSLV3 */ char * LDAP_server; /* Name or IP addr of X500 host*/ int LDAP_port; /* Port number of X500 host */ char * LDAP_user; /* User name for X500 host */ char * LDAP_password; /* Password of X500 host */ gsk_ca_roots LDAP_CA_roots; /* Which CA roots to use */ gsk_auth_type auth_type /* Client authentication type */ } gsk_init_data;

131


Los campos en la estructura gsk_init_data se describen en la tabla a

continuación.

Field Descripción

sec_types Especifica una cadena de caracteres terminada en nulo que identifica el protocolo de seguridad mínimo aceptable Versión a utilizar. El valor debe estar en mayúsculas caracteres. Los valores válidos son: • SSL30 para la versión 3.0 del protocolo. Esto se ajusta al estándar SSL 3.0 como lo define Netscape, que ahora ha sido entregado al IETF y renombrado TLS. • TLS10 para la versión 3.1 del protocolo. Esto se ajusta al protocolo TLS 1.0 como se define en RFC2246. • TLS11 para la versión 3.2 del protocolo. Esto se ajusta al protocolo TLS 1.1 como se define en RFC4346. • TLS12 para la versión 3.3 del protocolo. Esto se ajusta al protocolo TLS 1.2 como se define en RFC5246. Nota: Los clientes deben establecer este campo en el más alto versión de protocolo que pueden soportar. Los servidores deben establecer este campo en el protocolo más bajo versión que está dispuesto a aceptar.

keyring Opcionalmente especifica una cadena de caracteres terminada en nulo que identifica la lib.sublib en la que la clave privada y los certificados se almacenan. El nombre de la lib debe ser 7 caracteres o menos, seguidos de un punto, seguido del nombre de sublib y terminó con un carácter nulo (x'00 '). Un puntero nulo hace que la clave privada y los certificados leerse de los archivos de disco secuenciales predeterminados.

keyring_pw No utilizado.

keyring_stash No utilizado.

V2_session_timeout No utilizado.

V3_session_timeout Especifica el número de segundos en que un servidor permite que un cliente se vuelva a conectar sin realizar un proceso completo apretón de manos SSL. La configuración recomendada para este campo es 86400, que es la cantidad de segundos en 24 horas. Una configuración de 0 deshabilita efectivamente la reconexión rápida opción y provoca un mayor consumo de CPU durante el proceso de apretón de manos porque requiere que todos los clientes realizar un apretón de manos SSL completo.

LDAP_server No utilizado.

LDAP_port No utilizado.

132


Field Descripción

LDAP_user No utilizado. LDAP_password No utilizado. gsk_ca_roots Especifica qué raíces de CA utilizar para el certificado del

cliente autenticación. Los valores válidos son 0 y 1. Cuando un la aplicación quiere permitir la autenticación del cliente con certificados emitidos por la misma autoridad de certificación que VSE, debería usar un valor de 1.

gsk_auth_type Especifica el método a utilizar para verificar el cliente certificado. Este campo se usa solo cuando el campo gsk_ca_roots se establece en 1. Los valores válidos son 0 for Client_auth_local 1 for Client_auth_strong_over_ssl 2 for Client_auth_strong 3 for Client_auth_passthru


Código de retorno

Descripción


Non-zero Ocurrió un error. Consulte la sección "Depuración Problemas” en la página 194.

Notas de uso:

• Puede realizar múltiples llamadas a gsk_initialize () siempre que llame

gsk_uninitialize () para limpiar el SSL / TLS existente para VSE entorno antes de la

próxima llamada.


y llame al punto de entrada IPCRINIT contenido en el objeto IPCRYPTS cubierta.





133


gsk_secure_soc_close( ) Esta función finaliza una conexión de socket segura y libera todos los SSL / TLS

para Recursos VSE para esa conexión. La sintaxis es la siguiente:

#include <sslvse.h> void gsk_secure_soc_close(gsk_soc_data * user_socket);


Parámetro Descripción user_socket Apunta a la estructura gsk_soc_data devuelta desde Llamada



Código de retorno

Descripción


Non-zero Ocurrió un error. Consulte la sección "Depuración Problemas” en la página 194.

Nota de seguridad:

Esta nota describe una medida para prevenir ataques de truncamiento de hackers. TCP / IP FOR VSE siempre envía una alerta close_notify según lo requiera el especificación de protocolo, pero otras aplicaciones que no son VSE pueden no cumplir Con la especificación. Esto puede hacer que una aplicación en VSE se bloquee durante la finalización de la sesión mientras espera una alerta close_notify. A evitar este problema, TCP / IP FOR VSE no requiere una notificación de cierre alerta para ser recibido para completar un cierre.

Puede cambiar este comportamiento predeterminado configurando la palabra clave SSLFLG1 a $ OPTSRQC en la fase de opciones $ SOCKOPT. Cuando esta opción es configurado, TCP / IP FOR VSE requiere que se reciba una alerta close_notify durante un gsk_secure_soc_close. Esto significa que un cierre seguro no completar con éxito a menos que se reciba una alerta close_notify del Aplicación sin VSE.

CSI International recomienda que todos los clientes usen $ OPTSRQC opción para evitar ataques de truncamiento. Cada sitio debe sopesar el riesgo de problemas causados por aplicaciones que no cumplen con el protocolo especificación de intercambio de alertas close_notify antes de terminar un conexión. Si no configura esta opción, entonces sus aplicaciones pueden ser susceptibles a ataques de truncamiento.

Consulte el “Apéndice A: Fase de opciones de $ SOCKOPT”, página 196, para obtener detalles sobre establecer opciones en una fase de opciones personalizadas.

134


Notas de uso:

• Esta función libera todo el almacenamiento al que hace referencia el

usuario_socket parámetro.

• La aplicación de usuario debe cerrar todos los descriptores de socket abiertos

por cualquier socket API. Esta función no cierra ningún descriptor de socket

abierto.


y llame al punto de entrada IPCRSCLS contenido en el objeto IPCRYPTS cubierta.


detalladas.



135


gsk_secure_soc_init( ) Esta función inicializa las áreas de datos necesarias para SSL / TLS para que VSE

iniciar o aceptar una conexión de socket segura. Después de la función se

completa con éxito, se devuelve un identificador a la aplicación. Otro Las

llamadas que utilizan esta conexión de socket segura deben utilizar este

identificador.


#include <sslvse.h> gsk_soc_data * gsk_secure_soc_init( gsk_soc_init_data * soc_init_data);


Parámetro Descripción soc_init_data Puntero al área gsk_soc_init_data

Durante la llamada, se realiza un protocolo de enlace SSL completo basado en

entrada especificada en la estructura gsk_soc_init_data. Mientras SSL / TLS para

VSE realiza la mecánica del protocolo de enlace SSL, la aplicación debe

proporcionar las rutinas necesarias para transportar los datos SSL durante el SSL

apretón de manos, así como para todas las operaciones posteriores de lectura /

escritura. Ver el Notas de uso a continuación para obtener información sobre

cómo rechazar currículums rápidos.

La estructura gsk_soc_init_data específica las características de la seguridad

conexión de enchufe. Además, SSL / TLS para VSE utiliza esta estructura para

devolver información sobre la conexión de socket segura después de que sea

establecido. El área gsk_soc_init_data tiene la siguiente estructura:

typedef struct gsk_soc_init_data { int fd; /* Socket descriptor */ gsk_handshake hs_type; /* Client or server handshake */ char * DName; /* Key ring entry name */ char * sec_type; /* Type of security protocol used to protect this socket */ char * cipher_specs; /* Cipher specs choice and order for SSLV2 */ char * v3cipher_specs; /* Cipher specs choice and order for SSLV3 */ int (* skread) /* User-defined READ func pointer */ (int fd, void * buffer, int numbytes); int (* skwrite) /* User-defined WRITE func pointer*/ (int fd, void * buffer, int num_bytes); unsigned char cipherSelected[3]; /* V2 CipherSpec used */ unsigned char v3cipherSelected[2]; /* V3 CipherSpec used */ int failureReasonCode; /* Failure reason code */ gsk_cert_info * cert_info; /* Used during client authentication*/ gsk_init_data * gsk_data; /* Required for password exchange during DName negotiation */ } gsk_soc_init_data;

136


Los campos en la estructura gsk_soc_init_data se describen en la tabla abajo.

Field Descripción fd Descriptor de socket para esta conexión. La toma la dirección del

descriptor se pasa a la aplicación rutinas especificadas en los campos skread y skwrite. Estas las rutinas proporcionadas por la aplicación usan el socket descriptor según sea necesario para leer / escribir datos SSL. Nota 1: SSL / TLS no emite llamadas de socket para VSE utilizando el descriptor de socket. Es la dirección de un token que se pasa a la lectura de socket proporcionada por el usuario y escribir rutinas de salida. Puede almacenar la dirección de un área de trabajo dinámica como descriptor de socket, y cuando tu salida toma el control tienes fácil direccionabilidad a su área de trabajo que contiene su descriptor de socket real. Nota 2: el socket debe crearse, abrirse y conectado antes de llamar a gsk_secure_soc_init ().

hs_type Especifica cómo se realiza el protocolo de enlace SSL. Válido los valores son • GSK_AS_SERVER para realizar el protocolo de enlace SSL como servidor sin autenticación del cliente. • GSK_AS_SERVER_WITH_CLIENT_AUTH para realizar el protocolo de enlace SSL como servidor que requiere cliente autenticación. • GSK_AS_CLIENT para realizar el protocolo de enlace SSL como cliente con o sin autenticación de cliente. • GSK_AS_CLIENT_NO_AUTH para realizar el SSL Apretón de manos como cliente sin autenticación del cliente.

DName Apunta a una cadena de caracteres terminada en nulo del nombre de miembro de la biblioteca para .cert, .root y .prvk archivos para leer del llavero lib.sublib. El nombre del miembro debe tener ocho caracteres o menos en longitud y debe terminar con un carácter nulo (x'00 '). Para usar archivos de disco secuenciales, especifique SDFILES.

137


Field Descripción

sec_type Después de que un zócalo se conecta correctamente, este contiene un puntero a una cadena de caracteres terminada en nulo que identifica la versión del protocolo de seguridad establecida por el aplicación de servidor durante el proceso de protocolo de enlace: • SSL30 para la versión 3.0 del protocolo. Esta se ajusta al estándar SSL 3.0 según lo definido por Netscape • TLS31 para la versión 3.1 del protocolo. Esta cumple con el protocolo TLS 1.0 como se define en RFC2246. • TLS11 para la versión 3.2 del protocolo. Esta cumple con el protocolo TLS 1.1 como se define en RFC4346. • TLS12 para la versión 3.3 del protocolo. Esta cumple con el protocolo TLS 1.2 como se define en RFC5246.

cipher_specs Especifica una cadena de caracteres terminada en nulo que contiene la lista de cifrados SSL Versión 2.0 en orden de preferencia de uso. Este campo NO ES UTILIZADO por SSL / TLS para VSE.

v3cipher_specs Especifica una cadena de caracteres terminada en nulo que contiene la lista de cifrados SSL / TLS en orden de uso preferencia. Los valores válidos son: 01 para RSA-NULL-MD5 02 para RSA-NULL-SHA 08 para RSA-SDES040-SHA 09 para RSA-SDES056-SHA 0A para RSA-TDES168-SHA 2F para RSA-AES128-SHA 35 para RSA-AES256-SHA Puede usar cualquier combinación de estos valores en cualquier orden. El nivel de criptografía instalado en el el sistema puede invalidar algunos valores. Ver gsk_get_cipher_info () para obtener información sobre determinar las especificaciones de cifrado admitidas por el sistema. Si especifica un valor NULL para cipher_specs, él se utilizan especificaciones de cifrado SSL / TLS predeterminadas. El valor por defecto los cifrados dependen de la palabra clave SSLCIPH en $ SOCKOPT. Consulte el "Apéndice A: Fase de opciones de $ SOCKOPT" página 196, para obtener detalles sobre la configuración de opciones en una configuración personalizada fase de opciones.

138


Field Descripción

Skread Señala una rutina proporcionada por la aplicación que realiza una función de lectura para SSL / TLS para VSE. Los parámetros para esta rutina deben definirse como especificado en skread. Esta rutina provista por la aplicación debe usar convenciones de vinculación estándar. SSL / TLS para VSE utiliza la rutina skread mientras realiza el Protocolo de enlace SSL durante la llamada a gsk_secure_soc_init () y la llamada a gsk_secure_soc_read (). El skread La rutina contiene el siguiente código, que utiliza el sockets recv () llamada para leer los datos para el SSL conexión: int skread( int fd, void &data, int len ) { return( recv( fd, data, len, 0 ) ); }

La rutina skread debe devolver uno de los siguientes: • Un valor positivo para indicar el número de bytes. recibido • Un valor negativo para indicar que un error ocurrió. Si el código de retorno se establece en cero, el La función gsk_secure_soc_init () volverá a emitir la llamada a skread hasta un código de retorno positivo o negativo esta recibido.

Skwrite Señala una rutina de I/O proporcionada por la aplicación que realiza una función de escritura para SSL / TLS para VSE. Los parámetros para esta rutina deben definirse como especificado en skwrite. Esta I/O proporcionada por la aplicación la rutina debe usar convenciones de vinculación estándar. SSL / TLS para VSE usa la rutina skwrite mientras realizando el protocolo de enlace SSL durante el llamada gsk_secure_soc_init () y el Llamada gsk_secure_soc_write (). La rutina de skwrite contiene el siguiente código, que usa los sockets llamada send () para escribir los datos para la conexión SSL: int skwrite( int fd, void &data, int len) { return( send( fd, data, len, 0 ) ); }

La rutina skwrite debe devolver uno de los siguientes: • Un valor positivo para indicar el número de bytes. expedido • Un valor negativo para indicar que un error ocurrió si el código de retorno se establece en cero, la conexión SSL se dará por terminado.

139


Field Descripción

cipherSelected Especifica la especificación de cifrado arquitectónico SSL versión 2.0 valor seleccionado para esta sesión. SSL / TLS para VSE no es compatible con el estándar SSL 2.0.

V3cipherSelected Especifica la especificación de cifrado arquitectónico SSL versión 3.0 valor seleccionado para esta sesión, por ejemplo, 0X00,0X09.

failureReasonCode Especifica el código de razón de falla para gsk_secure_soc_init ().

cert_info Especifica los componentes de nombre distinguido de El certificado del cliente. Este parámetro solo es válido cuando se solicita la autenticación del cliente para un servidor usando SSL. Al finalizar con éxito, este campo contiene un puntero a la siguiente estructura, que es también contenido en <sslvse.h>:

typedef struct gskcertinfo { char * cert_body; /* Base64 certificate body */ int cert_body_len; /* Length of base64 cert body */ char * sessionID; /* Session ID for this connection */ int newSessionID; /* Flag to indicate if new session */ char * serial_num; /* Certificate Serial number */ char * common_name; /* Common Name of client */ char * locality; /* Locality */ char * state_or_province; /* State or Province */ char * country; /* Country */ char * org; /* Organization */ char * org_unit; /* Organizational unit */ char * issuer_common_name; /* Issuer’s common name */ char * issuer_locality; /* Issuer’s locality */ char * issuer_state_or_province; /* Issuer’s sta or prov */ char * issuer_country; /* Issuer’s country */ char * issuer_org; /* Issuer’s organization */ char * issuer_org_unit; /* Issuer’s organizational unit*/ } gsk_cert_info; gsk_data Apunta a la estructura gsk_init_data. Debes especifique

la dirección del mismo gsk_init_data estructura que se usó durante el gsk_initialize () Llamada de función.

140



Código de retorno

Descripción

Valor positivo Completar con éxito. El valor es un puntero a una estructura de tipo gsk_soc_data. Guarde este puntero: el estructura se utiliza en SSL / TLS posterior para VSE operaciones La estructura gsk_soc_data se define en <sslvse.h> como sigue:

Cero o un valor negativo

Ocurrió un error. Consulte la sección "Depuración Problemas” en la página 194.

Notas de uso:

• Puede bloquear currículums rápidos configurando la palabra clave SSLFLG1 en

$ OPTSNFR (Reanudación rápida no permitida) en las opciones $ SOCKOPT fase.

Establecer esta opción hace que una aplicación de servidor SSL / TLS rechazar

todas las solicitudes de reanudación rápida. La reanudación rápida puede

mejorar el rendimiento, pero algunos sitios pueden considerarlo como una

exposición de seguridad. Cuando rápido el currículum está deshabilitado, se

realiza un protocolo de enlace SSL / TLS completo para todos negociaciones de

sesión.

Consulte el “Apéndice A: Fase de opciones de $ SOCKOPT”, página 196, para

más detalles sobre la configuración de opciones en una fase de opciones

personalizadas.

• El descriptor de socket debe estar abierto y conectado antes de llamar a esta

rutina. Para las operaciones de socket, esto implica que un cliente debe realizar

las llamadas socket () y connect () antes de gsk_secure_soc_init () llamada. Para

los servidores, esto implica que el servidor debe realizar el socket (), bind (),

listen () y accept () llamadas antes de Llamada gsk_secure_soc_init ().


y llame al punto de entrada IPCRSINI contenido en el objeto IPCRYPTS cubierta.





141


gsk_secure_soc_read( ) Esta función recibe datos en una conexión de socket segura utilizando el rutina

de lectura especificada por la aplicación.


#include <sslvse.h> int gsk_secure_soc_read(gsk_soc_data * user_socket, void * data_buffer, int buffer_length);


Parámetro Descripción user_socket Puntero al área gsk_soc_init_data data_buffer Puntero al búfer proporcionado por el usuario en el que los

datos van a ser almacenados buffer_length Especifica la longitud de data_buffer


Código de retorno

Descripción

Cero o un valor positivo

Completar con éxito. El valor es el número de bytes leídos.

Valor negativo Ocurrió un error. Consulte la sección "Depuración Problemas” en la página 194.

Notas de uso: • La longitud máxima de los datos devueltos no puede exceder los 32K. Esto es porque SSL es un protocolo de nivel de registro en el que el registro más grande permitido es 32K menos los encabezados de registro SSL necesarios.

• Mezclando llamadas a gsk_secure_soc_read () y cualquiera de los socket leídos La función de recibir llamadas, aunque sea posible, no se recomienda. Esta requiere una correspondencia muy estrecha de las operaciones entre el cliente y el servidor programas Si alguna parte de un registro SSL se lee usando un socket leído función, se detecta un error grave de protocolo SSL cuando la próxima Se realiza gsk_secure_soc_read ().

• SSL / TLS para VSE se puede mezclar con lecturas y escrituras de socket, pero debe realizarse en conjuntos coincidentes. Si una aplicación cliente escribe 100 bytes de datos que utilizan una o más de las llamadas de envío de socket, luego en la aplicación del servidor debe leer exactamente 100 bytes de datos usando uno o más del socket recibe llamadas. Esto también es cierto para gsk_secure_soc_read () y gsk_secure_soc_write ().

142


• Debido a que SSL es un protocolo orientado a registros, debe recibir un

protocolo completo registrar antes de que se descifre y cualquier dato se

devuelva al solicitud. Por lo tanto, un select () puede indicar que los datos están

disponibles para ser leer, pero un gsk_secure_soc_read () posterior puede

colgarse mientras espera para que se reciba el resto del registro SSL.


y llame al punto de entrada IPCRSRED contenido en IPCRYPTS cubierta de





143


gsk_secure_soc_reset( ) Esta función actualiza los parámetros de seguridad, como las claves de cifrado,

para una sesión También puede usarlo para reanudar o reiniciar una sesión en

caché.


#include <sslvse.h> int gsk_secure_soc_reset(gsk_soc_data * user_socket);


Parámetro Descripción user_socket Apunta a la estructura gsk_soc_data devuelta desde Llamada



Código de retorno

Descripción

Cero Completar con éxito.

No cero Ocurrió un error. Consulte la sección "Depuración Problemas” en la página 194.

Notas de uso:

• Utilice gsk_secure_soc_reset () cuando un cliente o servidor necesite

restablecer el entorno SSL. Llame a gsk_secure_soc_reset () solo después de un

éxito llame a gsk_secure_soc_init (). Además, use gsk_secure_soc_reset ()

cuando reanudar o reiniciar una conexión para una sesión SSL que fue en caché y

al restablecer las claves utilizadas para esa conexión.


y llame al punto de entrada IPCRSRST contenido en el objeto IPCRYPTS cubierta.





144


gsk_secure_soc_write( ) Esta función envía datos en una conexión de socket segura utilizando el rutina de

escritura especificada por la aplicación. La sintaxis es la siguiente:

#include <sslvse.h> int gsk_secure_soc_write(gsk_soc_data * user_socket, void * data_buffer, int buffer_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción user_socket Puntero a gsk_soc_data. data_buffer Puntero al búfer proporcionado por el usuario en el que los

datos para ser escrito se almacena. buffer_length Especifica la longitud de data_buffer. El máximo permitido es

65536 bytes.


Código de retorno

Descripción

Cero o valor positivo

Completar con éxito. El valor es el número de bytes escritos.

Valor negativo Se produjo un error. Consulte "Problemas de depuración" en la página 194.

Notas de uso:

• Si los datos de la aplicación enviados a una aplicación SSL / TLS para VSE son más que 32K, debe realizar varias llamadas a gsk_secure_soc_read () en para leer todo el bloque de datos de la aplicación.

• SSL / TLS para lecturas y escrituras de VSE se pueden mezclar con lecturas de socket y escribe, pero deben realizarse en conjuntos coincidentes. Si un cliente la aplicación escribe 100 bytes de datos usando uno o más de los sockets enviar llamadas, entonces la aplicación del servidor debe leer exactamente 100 bytes de los datos que utilizan uno o más de los sockets reciben llamadas. Esto también es cierto para gsk_secure_soc_read () y gsk_secure_soc_write (). Si un búfer de escritura está separado en múltiples buffers, el sitio remoto del socket seguro la conexión debe realizar suficientes operaciones gsk_secure_soc_read () para leer el búfer completo.

• Para Assembler, use macro SSLVSE para generar las áreas de datos requeridas y llame al punto de entrada IPCRSWRT contenido en IPCRYPTS cubierta de objetos Vea los programas de muestra SSLSERVR y SSLCLINT para especificaciones detalladas de la interfaz del ensamblador.

• Para obtener información sobre la compatibilidad con el protocolo TLS 1.2, consulte el “Apéndice C: Mejora de TLS 1.2 ”en la página 208.

145


gsk_uninitialize( ) Esta función elimina la configuración general actual para el SSL ambiente.

Elimina campos como valores de tiempo de espera de sesión y SSL protocolos.


#include <sslvse.h> int gsk_uninitialize(void);


Código de retorno

Descripción

Cero Completar con éxito..

No cero Se produjo un error. Consulte "Problemas de depuración" en la página 194.

Notas de uso:

• Use gsk_uninitialize () cuando necesite restablecer el SSL del sistema ajustes

del entorno Luego, use gsk_initialize () para crear un nuevo conjunto de

Configuración del entorno SSL del sistema.

• Debe cerrar todas las sesiones SSL que se crearon utilizando el actual Entorno

SSL del sistema antes de llamar a gsk_uninitialize ().


y llame al punto de entrada IPCRUNIN contenido en IPCRYPTS cubierta de





146


gsk_user_set( ) SSL / TLS no utiliza esta función para la API de VSE, pero es mantenido para la

portabilidad de las aplicaciones OS / 390.


#include <sslvse.h> int gsk_user_set(int user_data_fid, void * user_input_data, void * reserved);


Parámetro Descripción user_data_fid Especifica la acción a realizar. user_input_data Especifica la información requerida para el pedido acción. Reserved Un campo reservado; especifíquelo como nulo.


Código de retorno

Descripción


No cero Se produjo un error. Consulte "Problemas de depuración" en la página 194.

Notas de uso:


y llame al punto de entrada IPCRUSET contenido en IPCRYPTS cubierta de





147


CryptoVSE API

Visión general SSL / TLS para VSE proporciona una API criptográfica que puede usar para

implementar algoritmos criptográficos en una aplicación VSE. Los algoritmos

proporcionan confidencialidad, autenticación e integridad de los datos en las

aplicaciones.

Hay muchos buenos sitios web y libros que tratan sobre criptografía, y está más

allá del alcance de este documento proporcionar un tratamiento del tema. Para

aprender más sobre los algoritmos implementado en esta API y cómo se usan,

consulte "Publicado Estándares "y" Referencias "en el capítulo" SSL / TLS para

VSE "en el TCP / IP PARA VSE Guía de características opcionales.

Esta API proporciona los siguientes servicios criptográficos:

• Cifrado de datos:

AES 128, 192 y 256 basado en FIPS Pub 197

DES basado en FIPS Pub 46-3

Triple DES basado en ANSI X9.52 Triple DES

RSA PKCS # 1 también contenido en RFC2313

• Resúmenes de mensajes:

MD5 basado en RFC1321

SHA-1 basado en FIPS Pub 180-1

• Autenticación de mensaje:

HMAC basado en RFC2104

• Firmas digitales:

RSA PKCS # 1 con un resumen de mensaje SHA1 o MD5

• Varios:

Codificación universal de caracteres imprimibles

Generación de números aleatorios (RNG)

SSL / TLS pseudo RNG como se documenta en RFC2246

Las funciones que componen la API criptográfica se describen en las siguientes

páginas de esta sección.

Nota: debe emitir la llamada cry_initialize () antes de emitir cualquier otro

Crypto llamadas. Esta llamada inicializa el entorno para la criptografía funciones.

148


cry_3des_cbc_encrypt( ) Esta función utiliza el algoritmo Triple DES en CBC (Cipher Block

Encadenamiento) para encriptar los datos pasados.


#include <sslvse.h> int cry_3des_cbc_encrypt( &input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción Input Referencia a los datos a cifrar. input_length Longitud de los datos a cifrar. Key Referencia a los datos clave para el cifrado. key_length Longitud de los datos clave para el cifrado. Workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos 256

bytes de largo.


Código de retorno

Descripción



Notas de uso:

• La longitud de los datos debe ser un múltiplo de 8 bytes.

• La longitud de la clave debe ser de 32 bytes. Los primeros 8 bytes contienen el

vector de inicialización, que es seguido por la clave de 24 bytes.

• Para el ensamblador, llame al CRYTDESE vcon con los mismos parámetros.

149


cry_3des_cbc_decrypt( ) Esta función utiliza el algoritmo Triple DES en CBC (Cipher Block

Encadenamiento) para descifrar los datos pasados.


#include <sslvse.h> int cry_3des_cbc_decrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción input Referencia a los datos a cifrar. input_length Longitud de los datos a cifrar. key Referencia a los datos clave para el cifrado. key_length Longitud de los datos clave para el cifrado. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos 256

bytes de largo.


Código de retorno

Descripción



Notas de uso:



vector de inicialización, seguido de la clave de 24 bytes.

• Para Assembler, llame al CRYTDESD vcon con los mismos parámetros.

150


cry_aes128_cbc_encrypt( ) Esta función utiliza el algoritmo AES 128 en CBC (Cipher Block Encadenamiento)

para encriptar los datos pasados.


#include <sslvse.h> int cry_aes128_cbc_encrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:


• La longitud de la clave debe ser de 32 bytes. Los primeros 16 bytes contienen

el vector de inicialización, seguido de la clave de 16 bytes.

• Para Assembler, llame al CRYA12EC vcon con los mismos parámetros.

151


cry_aes128_cbc_decrypt( ) Esta función utiliza el algoritmo AES 128 en CBC (Cipher Block Encadenamiento)

para descifrar los datos pasados.


#include <sslvse.h> int cry_aes128_cbc_decrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:


• La longitud de la clave debe ser de 16 bytes.

• Para Assembler, llame al CRYA12EE vcon con los mismos parámetros.

153


cry_aes128_ecb_decrypt( ) Esta función utiliza el algoritmo AES 128 en modo ECB (retroalimentación

electrónica) para descifrar los datos pasados.


#include <sslvse.h> int cry_eas128_ecb_decrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:



• Para Assembler, llame al CRYA12DE vcon con los mismos parámetros.

154





#include <sslvse.h> int cry_aes192_cbc_encrypt(&input, input_length, &key, key_length, &workarea, work_length);



bytes de largo.


Código de retorno

Descripción



Notas de uso:





155





#include <sslvse.h> int cry_aes192_cbc_decrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:




• Para el ensamblador, llame al CRYA19DC vcon con los mismos parámetros.

156


cry_aes192_ecb_encrypt( ) Esta función utiliza el algoritmo AES 192 en ECB (retroalimentación electrónica)

modo para cifrar los datos pasados.


#include <sslvse.h> int cry_aes192_ecb_encrypt(&input, input_length, &key, key_length, &workarea, work_length);



bytes de largo.


Código de retorno

Descripción



Notas de uso:




157





#include <sslvse.h> int cry_aes192_ecb_decrypt(&input, input_length, &key, key_length, &workarea, work_length);



bytes de largo.


Código de retorno

Descripción



Notas de uso:




158





#include <sslvse.h> int cry_aes256_cbc_encrypt(&input, input_length, &key, key_length, &workarea, work_length);



bytes de largo.


Código de retorno

Descripción



Notas de uso:





159





#include <sslvse.h> int cry_aes256_cbc_decrypt(&input, input_length, &key, key_length, &workarea, work_length);



bytes de largo.


Código de retorno

Descripción



Notas de uso:




• Para el ensamblador, llame al CRYA25DC vcon con los mismos parámetros.

160


cry_aes256_ecb_encrypt( ) Esta función utiliza el algoritmo AES 256 en ECB (retroalimentación electrónica)

modo para cifrar los datos pasados.


#include <sslvse.h> int cry_aes256_ecb_encrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:




161





#include <sslvse.h> int cry_aes256_ecb_decrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:




162


cry_des_cbc_encrypt( ) Esta función utiliza el algoritmo DES en CBC (Cipher Block Chaining) modo para

cifrar los datos pasados.


#include <sslvse.h> int cry_des_cbc_encrypt(&input, input_length, &key, key_length, &workarea, work_length);



bytes de largo.


Código de retorno

Descripción



Notas de uso:




• Para Assembler, llame al CRYDECBE vcon con los mismos parámetros.

163


cry_des_cbc_decrypt( ) Esta función utiliza el algoritmo DES en CBC (Cipher Block Chaining) modo para

descifrar los datos pasados.


#include <sslvse.h> int cry_des_cbc_decrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:




• Para el ensamblador, llame al CRYDECBD vcon con los mismos parámetros.

164


cry_des_encrypt( ) Esta función utiliza el algoritmo DES para cifrar los datos pasados.


#include <sslvse.h> int cry_des_encrypt(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:


bytes de largo.


Código de retorno

Descripción



Notas de uso:

• La longitud de los datos debe ser un múltiplo de 8 bytes, y la longitud de la

clave debe ser de 8 bytes.

• Para Assembler, llame al CRYDESEC vcon con los mismos parámetros.

165


cry_des_decryt( ) Esta función utiliza el algoritmo DES para descifrar los datos pasados.


#include <sslvse.h> int cry_des_decrypt(&input, input_length, &key, key_length, &workarea, work_length);



bytes de largo.


Código de retorno

Descripción



Notas de uso:

• La longitud de los datos debe ser un múltiplo de 8 bytes, y la longitud de la

clave debe ser de 8 bytes.

• Para Assembler, llame al CRYDESDC vcon con los mismos parámetros.

166


cry_gen_random( ) Esta función utiliza una tarjeta de hardware de cripto-coprocesador para generar

un número aleatorio.


#include <sslvse.h> int cry_gen_random(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción input Puntero al área de datos aleatorios. input_length Longitud del área de datos aleatorios. El máximo es 2048. key Debe suministrarse pero no se utiliza. key_length Debe suministrarse pero no se utiliza. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción

Valor positivo Completar con éxito. El valor es el actual número de bytes aleatorios generados y debe ser igual a la longitud de entrada pasada.


Notas de uso:

• Esta función requiere una tarjeta de criptocoprocesador.

• Para Assembler, llame a CRYGENRA vcon con los mismos parámetros.

167


cry_get_cert_info( ) Esta función recupera información de sujeto y emisor de una PKI Certificado

X.509v3.


#include <sslvse.h> int cry_get_cert_info(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia al certificado X.509v3 de entrada para ser

descifrado. input_length Duración del certificado de entrada. key Referencia al área que contiene el certificado información. key_length Longitud del área de información del certificado. Debe ser

mayor de 64 bytes. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• La información del certificado que se devuelve es la misma que cert_info

estructura que se devuelve desde un gsk_secure_soc_init con el cliente

autenticación.

• Para Assembler, llame al CRYGCRIN vcon con los mismos parámetros.

168


cry_hmac_md5( ) Esta función crea un hash con clave MD5, también conocido como MAC (Código

de autenticación de mensaje) de los datos pasados.


#include <sslvse.h> int cry_hmac_md5(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia a los datos de entrada para el hash. input_length Longitud de los datos de entrada para el hash. key Referencia a los datos clave para el MAC. key_length Longitud de los datos clave para el MAC. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• Se devuelve un MAC MD5 de 16 bytes en el área de trabajo suministrada por el

usuario.

• Para Assembler, llame al CRYHMMD5 vcon con los mismos parámetros.

169


cry_hmac_sha( ) Esta función crea un hash con clave SHA, también conocido como MAC (Código

de autenticación de mensaje) de los datos pasados.


#include <sslvse.h> int cry_hmac_sha(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción input Referencia a los datos de entrada para el hash. input_length Longitud de los datos de entrada para el hash. key Referencia a los datos clave para el MAC. key_length Longitud de los datos clave para el MAC. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• Se devuelve un MAC SHA-1 de 20 bytes en el área de trabajo suministrada por

el usuario.

• Para Assembler, llame al CRYHMSHA vcon con los mismos parámetros.

170


cry_initialize( ) Esta función inicializa el entorno para las funciones de criptografía.


#include <sslvse.h> int cry_initialize(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción input No utilizado input_length No utilizado key No utilizado key_length No utilizado workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• Esta llamada de inicialización debe hacerse antes de emitir cualquier otra

criptografía llamada.

• Esta llamada se abre y lee el certificado RSA, la raíz y los archivos de clave.

• Para Assembler, llame al CRYINITI vcon con los mismos parámetros.

171


cry_md5_hash( ) Esta función utiliza el algoritmo MD5 (RSA Message Digest 5) para crear un hash

de los datos pasados.


#include <sslvse.h> int cry_md5_hash(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia a los datos de entrada para el hash. input_length Longitud de los datos de entrada para el hash. key Debe suministrarse pero no se utiliza. key_length Debe suministrarse pero no se utiliza. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• Se devuelve un hash MD5 de 16 bytes en el área de trabajo suministrada por el

usuario.

• Para el ensamblador, llame al CRYMD5HA vcon con los mismos parámetros.

172


cry_rsa_encrypt( ) Esta función utiliza el algoritmo RSA PKCS # 1 versión 1.5 para cifrar los datos

pasados.


#include <sslvse.h> int cry_rsa_encrypt(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia a los datos a cifrar. input_length Longitud de los datos a cifrar. key Referencia a la clave RSA que se utilizará. key_length Longitud de los datos clave de RSA. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• Si la longitud de la clave es cero, entonces la clave RSA se lee del PRVKFIL

archivo de clave.

• Si la longitud de la clave no es cero, la persona que llama debe proporcionar la

clave RSA.

• El tamaño de la clave RSA determina el tamaño del bloque cifrado. Cuando Con

una clave de 512 bits, el bloque cifrado es de 64 bytes. Cuando se usa un Clave

de 1024 bits, el bloque cifrado es de 128 bytes.

• Para el ensamblador, llame al CRYRSAEC vcon con los mismos parámetros.

173


cry_rsa_decrypt( ) Esta función utiliza el algoritmo RSA PKCS # 1 versión 1.5 para descifrar Los datos

pasados.


#include <sslvse.h> int cry_rsa_decrypt(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia a los datos a descifrar. input_length Longitud de los datos a descifrar. key Referencia a la clave RSA que se utilizará. key_length Longitud de la clave RSA. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción

Valor positivo Completar con éxito. El valor es la longitud de la datos descifrados Los datos descifrados se superponen a la entrada área de datos.


Notas de uso:


archivo de clave.


clave RSA.

• Para Assembler, llame al CRYRSADC vcon con los mismos parámetros.

174


cry_rsa_genprvk( ) Esta función utiliza una tarjeta cripto-coprocesadora para generar un RSA

privado llave. La sintaxis es la siguiente:

#include <sslvse.h> int cry_rsa_genprvk(&area, area_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción input Puntero al área de clave privada RSA. input_length Longitud del área de clave privada RSA. key Debe suministrarse pero no se utiliza. key_length Puntero a un área de palabra completa que contiene el

tamaño de clave privada RSA que se generará. Esto debe ser 1024, 2048 o 4096.

workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción

Valor positivo Completar con éxito. El valor es el número de bytes en el blob de claves RSA generado. El área entonces contiene el blob de clave privada RSA generado.


Notas de uso:

• Esta función requiere una tarjeta de cripto-coprocesador.

• Para Assembler, llame al CRYGRSAP vcon con los mismos parámetros.

175


cry_rsa_signature_create( ) Esta función crea una firma digital basada en el RSA PKCS # 1 Versión 1.5

estándar.


#include <sslvse.h> int cry_rsa_signature_create(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción input Referencia a los datos de entrada para la firma. input_length Longitud de los datos de entrada. key Referencia a la clave RSA que se utilizará. key_length Longitud de la clave RSA. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción

Valor positivo Completar con éxito. El valor es la longitud de la Bloque de firma RSA. El bloque de firma se superpone El área de datos de entrada.


Notas de uso:


archivo de clave.


clave RSA.

• El tamaño de la clave RSA determina el tamaño del bloque de firma. Cuando

Con una clave de 512 bits, el bloque de firma es de 64 bytes. Cuando se usa un

Clave de 1024 bits, el bloque de firma es de 128 bytes.

• Para Assembler, llame al CRYRSASC vcon con los mismos parámetros.

176


cry_rsa_signature_verify( ) Esta función verifica una firma digital basada en el RSA PKCS # 1 Versión 1.5

estándar.


#include <sslvse.h> int cry_rsa_signature_verify(&input, input_length, &key, key_length, &workarea, work_length); Los parámetros se describen en la siguiente tabla:

Parámetro Descripción input Referencia a los datos de entrada para la firma verificación. input_length Longitud de los datos de entrada. key Referencia a la clave RSA que se utilizará. key_length Longitud de la clave RSA. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción

Valor positivo Completar con éxito. El valor es la longitud de la Bloque de firma RSA. El bloque de firma se superpone el área de datos de entrada.


Notas de uso:


archivo de clave.


clave RSA.

• Para el ensamblador, llame al CRYRSASV vcon con los mismos parámetros.

177


cry_sha_hash( ) Esta función utiliza el SHA (algoritmo de hash seguro) para crear un hash de los

datos pasados.


#include <sslvse.h> int cry_sha_hash(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia a los datos de entrada para el hash. input_length Longitud de los datos de entrada para el hash. key Debe suministrarse pero no se utiliza. key_length Debe suministrarse pero no se utiliza. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• Se devuelve un hash SHA-1 de 20 bytes en el área de trabajo suministrada por

el usuario.

• Para Assembler, llame al CRYSHAHA vcon con los mismos parámetros.

178


cry_sha2_hash( ) Esta función crea un hash de mensaje SHA-256 a partir de la entrada pasada

datos.


#include <sslvse.h> int cry_sha2_hash(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Puntero al área de datos de entrada. input_length Longitud del área de datos de entrada. key Debe suministrarse pero no se utiliza. key_length Debe suministrarse pero no se utiliza. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción

Cero Completar con éxito. Un hash de 32 bits, SHA de 256 bits se devuelve en el área de trabajo.


Notas de uso:

• Esta función requiere soporte de hardware para la instrucción KLMD, que

debería estar disponible en un procesador z10 o superior. Comprueba con su

proveedor de hardware de IBM para verificar que su sistema sea compatible con

esto función.

• Para el ensamblador, llame al CRYSHA2H vcon con los mismos parámetros.

179


cry_universal_print_encode( ) Esta función convierte datos binarios en imprimibles universalmente

caracteres.


#include <sslvse.h> int cry_universal_print_encode(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia a los datos de entrada para la codificación. input_length Longitud de los datos de entrada. key Debe suministrarse pero no se utiliza. key_length Debe suministrarse pero no se utiliza. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción



Notas de uso:

• La longitud de los datos de entrada debe ser de 48 bytes.

• Los 64 bytes de caracteres imprimibles universalmente se devuelven en área

de trabajo suministrada por el usuario.

• Para Assembler, llame al CRYUPENC vcon con los mismos parámetros.

180


cry_universal_print_decode( ) Esta función convierte los caracteres imprimibles universalmente a

binarios datos.


#include <sslvse.h> int cry_universal_print_decode(&input, input_length, &key, key_length, &workarea, work_length);


Parámetro Descripción input Referencia a los datos de entrada para la codificación. input_length Longitud de los datos de entrada. key Debe suministrarse pero no se utiliza. key_length Debe suministrarse pero no se utiliza. workarea Referencia a un área de trabajo. work_length Longitud del área de trabajo pasada. Debe ser al menos

256 bytes de largo.


Código de retorno

Descripción

Valor positivo Completar con éxito. El valor es la longitud de los datos binarios.


Notas de uso:

• La longitud de los datos de entrada debe ser de 64 bytes.

• Los 48 bytes de datos binarios se devuelven en el trabajo proporcionado por el

usuario zona.

• Para Assembler, llame al CRYUPDEC vcon con los mismos parámetros.

181


Common Encryption Cipher Interface

La interfaz de cifrado de cifrado común (CECI) es una interfaz las aplicaciones pueden llamar desde ensamblador, COBOL u otro nivel alto idiomas usando convenciones de enlace de llamada / guardar estándar. Está diseñado para separe la codificación del algoritmo de cifrado y los valores clave utilizados en un programa de aplicación desde la propia aplicación. Una fase separada es creada que contiene el algoritmo de cifrado y los valores de semilla clave de que se generan las claves. El cifrado y descifrado pueden ser realizado en la aplicación, y la semilla clave y el algoritmo pueden ser cambiado sin tener que cambiar la aplicación. También puedes agregar un hash seguro (SHA-1 o SHA-2) para garantizar la integridad de cada encriptado bloque de datos Defina el nombre de la fase y especifique el cifrado predeterminado y número de semilla clave que las aplicaciones pueden usar en un JCL de CIALSEED.

Esta interfaz cumple con los requisitos específicos de auditoría de VISA CISP estándar. Este estándar se ha incorporado a más que abarca el "Estándar de seguridad de datos de la industria de tarjetas de pago (PCI)" (DSS), que es publicado y aplicado por la industria de tarjetas de pago Consejo de Normas de Seguridad. Más información sobre este estándar es disponible en www.pcisecuritystandards.org.

Llamando al CIALCECI Para implementar la interfaz, su aplicación debe llamar al CIALCECI apunte y Stub pase el área de solicitud como primer parámetro para todas las solicitudes. El código auxiliar CIALCECI se carga y llama a la fase CIALCECZ, que realiza la obra. Estos componentes se distribuyen con TCP / IP PARA VSE 2.2 software. La aplicación debe incluir TCP / IP lib.sublib en Fase de la cadena de búsqueda de libdef en la partición donde está la aplicación corriendo.

En los programas de ensamblador, el código auxiliar se puede llamar de la siguiente manera:

LA R1,MEMADSCT Address of request area ST R1,PARM1 Store request area addr as 1st parm LA R1,PARMLIST Set address of parmlist into R1 L R15,=V(CIALCECI) Load entry address of CIALCECI stub BASR R14,R15 Enter CIALCECI .... PARMLIST DS 0F PARM1 DS F PARM2 DS F PARM3 DS F PARM4 DS F

En los programas COBOL, se puede llamar al código auxiliar utilizando el

comando CALL, como sigue:

CALL 'CIALCECI' USING CIALCECI-RQSTAREA

182

http://www.pcisecuritystandards.org/


Área de solicitud Todas las llamadas requieren que se pase un área de solicitud usando llamada /

guardar estándar enlace. Los campos del área de solicitud para COBOL y

Assembler se enumeran en las siguientes secciones. Una lista de las constantes

COBOL sigue la lista de campos COBOL.

Nota: En este capítulo, los campos del área de solicitud son referenciados por su

COBOL nombre. El nombre del ensamblador correspondiente sigue entre

paréntesis.

El campo CIALCECI-EYE-CATCHER (MEMAEYEC) debe establecerse en

"MEMAEYEC" y colocado al comienzo del área de solicitud.

COBOL Fields Los campos del área de solicitud COBOL son los siguientes:

01 CIALCECI-RQSTAREA. 05 CIALCECI-EYE-CATCHER PIC X(8). 05 CIALCECI-RQSTAREA-LEN PIC S9(8) COMP. 05 CIALCECI-REQ-CODE PIC S9(8) COMP. * 0 - INITIALIZE REQUEST * 4 - CREATE CIPHER KEY * 8 - ENCRYPT BLOCK * 12 - ENCRYPT DONE * 16 - DECRYPT BLOCK * 20 - ERASE KEY * 24 - RELEASE TOKEN 05 CIALCECI-RC PIC S9(4) COMP.

0 - REQUEST SUCCESSFULLY PROCESSED 05 CIALCECI-EXRC PIC S9(4) COMP. * 2 - ENCRYPT DATA BUFFERED NO DATA BLK TO WRITE * 4 - ENCRYPT DATA BUFFERED WRITE DATA BLOCK 05 CIALCECI-ERROR-DISP PIC S9(8) COMP. 05 CIALCECI-ERROR-REASON PIC X(8). 05 CIALCECI-KEY-PHASE PIC X(8). 05 CIALCECI-MAX-BLKSIZE PIC S9(8) COMP. 05 CIALCECI-TOKEN PIC S9(8) COMP. 05 CIALCECI-CURRENT-CIPHER PIC S9(8) COMP. 05 CIALCECI-CURRENT-KEY-NBR PIC S9(8) COMP. 05 CIALCECI-DATA-LEN PIC S9(8) COMP. 05 CIALCECI-DATA-ADDR USAGE IS POINTER. 05 CIALCECI-OUTPUT-LEN PIC S9(8) COMP. 05 CIALCECI-OUTPUT-ADDR USAGE IS POINTER. 05 CIALCECI-CIPHER-DESC PIC X(16). 05 FILLER PIC X(8).

Constante COBOL Las constantes del área de solicitud COBOL son las siguientes:

01 CIALCECI-CONSTANTS. 05 CAILCECI-REQ-INIT PIC S9(4) COMP VALUE +0. 05 CAILCECI-REQ-GEN-KEY PIC S9(4) COMP VALUE +4. 05 CAILCECI-REQ-ENCRYPT PIC S9(4) COMP VALUE +8. 05 CAILCECI-REQ-ENCRYPT-DONE PIC S9(4) COMP VALUE +12. 05 CAILCECI-REQ-DECRYPT PIC S9(4) COMP VALUE +16. 05 CAILCECI-REQ-ERASE-KEY PIC S9(4) COMP VALUE +20. 05 CAILCECI-REQ-REL-TOKEN PIC S9(4) COMP VALUE +24. 05 CAILCECI-RC-HAVE-DATA PIC S9(4) COMP VALUE +4.

183


Ensamblador Fields Los campos del área de solicitud del ensamblador se enumeran en la siguiente

tabla. Los nombres de campo de ecualización están sangrados.

Nombre de Field Almacenamiento Descripción MEMADSCT DSECT OD MEMAEYEC DS CL8 Llamativo MEMALENG DS F Longitud de este bloque de solicitud MEMARQST DS F Código de solicitud MEMAINIT EQU 0 Inicializar solicitud MEMACRKY EQU 4 Crear clave de cifrado MENAEBLK EQU 8 Cifrar bloque MEMAEDON EQU 12 Cifrar hecho MEMADBLK EQU 16 Descifrar bloque MEMAXKEY EQU 20 Clave de borrado MEMARTOK EQU 24 Token de liberación MEMARCOD DS H Código de retorno MEMARCOK EQU 0 Solicitud exitosa MEMAEXRC DS H Código de retorno extendido MEMAE002 EQU 2 Bueno MEMAEBLK, sin escritura de

datos MEMAE004 EQU 4 Buen MEMAEBLK, datos para

escribir MEMAEDSP DS F Desplazamiento de error MEMAERSN DS CL8 Motivo del error (visualizable) MEMAKYPH DS CL8 Nombre de fase de frase clave

(CIALSEED) MEMAMAXB DS F Tamaño de bloque máximo MEMATOKN DS F Token para todas las solicitudes MEMACIPH DS F Cifrado actual MEMAKNUM DS F Número de clave actual MEMALDAT DS F Longitud de datos pasados MEMA@DAT DS A Dirección de datos pasados MEMALOUT DS F Longitud de datos de salida

184


Nombre de Field Almacenamiento Descripción MEMA@OUT DS A Dirección de datos de salida MEMACIDE DS CL16 Descripción de cifrado DS D Reservado MEMARQSL EQU *-MEMAEXRC Longitud de toda el área de

solicitud

Códigos de retorno La aplicación debe verificar el código de retorno después de completar cada llamada al trozo CIALCECI. Para los programas de ensamblador, esto está en R15. Por Programas COBOL, esto está en el CÓDIGO DE RETORNO reservado por COBOL campo. El campo CIALCECI-RC (MEMARCOD) también contiene el retorno código a menos que el área de solicitud no comience con el requerido MEMAEYEC llamativo. En ambos casos (en R15 y en RETURNCODE), un valor de 0 indica que la solicitud fue procesada exitosamente.

Si una solicitud falla con un código de retorno distinto de cero, aparece un mensaje de error CCZ601 emitido que contiene la razón por la cual la solicitud falló. El código de razón también es establecido en el campo CIALCECI-ERROR-REASON (MEMAERSN) en el campo área de solicitud El desplazamiento del error en la fase CIALCECZ es establecido en el campo CIALCECI-ERROR-DISP (MEMAEDSP).

Hay una excepción tal que si el CDLOAD para el CIALCECZ.phase falla, luego el código de retorno se establece en -101. En este caso, el campo CIALCECI-RC (MEMARCOD) no está configurado.

Pseudocode cifrado Esta sección describe el pseudocódigo para implementar el cifrado en un solicitud. Debe realizar las siguientes solicitudes. El resto de esta sección explica cada paso.

1. Inicializar solicitud

2. Crear solicitud de material clave

3. Cifrar solicitud de datos

4. Solicitud encriptada

5. Solicitud de borrado de clave

6. Solicitud de token de lanzamiento

1. Inicializar Para la solicitud de inicialización, la aplicación debe establecer los siguientes campos:

• CIALCECI-REQ-CODE (MEMAEXRC) debe establecerse en CAILCECI-REQ-INIT (MEMAINIT).

• CIALCECI-MAX-BLKSIZE (MEMAMAXB) debe contener el tamaño máximo de bloque que pasa la aplicación. Este valor debe ser múltiplo de 16, y debe estar entre 256 y 65536 (64K).

185


• CIALCECI-KEY-PHASE (MEMAKYPH) debe contener el nombre de la fase generada que define el cifrado y las semillas clave disponibles. Consulte la sección CIALSEED JCL para obtener más información sobre cómo generar esta fase Las semillas clave se explican en el siguiente paso.

Una vez completada la inicialización, el área de solicitud contiene la dirección de un token que ha sido asignado. Debe pasar la misma área de solicitud y solo cambie los campos necesarios para una solicitud específica.

2. Crear clave Esta solicitud genera datos clave de frase semilla que especifique en CIALSEED JCL para ser ingresado a un generador de función pseudoaleatoria (PRF). Este generador crea el material clave para el cifrado que se utiliza.

¿Qué es un generador PRF y por qué lo usamos? Cifrado diferente Los algoritmos requieren diferentes cantidades (número de bytes) de material clave. Podemos usar un generador PRF con cualquier frase para generar la correcta cantidad de material clave para un cifrado seleccionado. Parte de la entrada al generador es una frase semilla que selecciona que puede ser alfanumérica o valor binario Este enfoque crea una clave muy segura y no deja el valor real de la clave expuesta.

Puede definir múltiples frases semilla en el CIALSEED JCL. Cada semilla la definición de frase está asociada con un número clave. Debes establecer un valor predeterminado número clave en el JCL de este grupo de definiciones de frases. También debe establecer un algoritmo de cifrado / hash predeterminado.

Para la solicitud de creación de clave, la aplicación debe establecer los siguientes campos:

• CIALCECI-REQ-CODE (MEMAEXRC) debe establecerse en CAILCECI-REQ-GEN-KEY (MEMACRKY).

• CIALCECI-CURRENT-CIPHER (MEMACIPH) y CIALCECI-CURRENT-KEY-NBR (MEMAKNUM) se establecen en cifrado / hash predeterminado y número de clave, respectivamente, durante el anterior Inicializar solicitud de los valores definidos en el CIALSEED-generado fase.

Puede anular los valores predeterminados en una aplicación estableciendo estos solicitar campos de área a otros valores válidos. Las combinaciones de cifrado / hash puede seleccionar se enumeran en el JCL de muestra en una sección posterior. La clave el número que use debe definirse en la fase generada por CIALSEED. Ver Cipher Suite Selection para obtener más información sobre cómo seleccionar un apropiado combinación de cifrado / hash.

3. Cifrar datos Puede pasar cualquier número de bytes menor o igual que Valor CIALCECI-MAX-BLKSIZE (MEMAMAXB).

Para la solicitud de cifrado de datos, la aplicación debe establecer lo siguiente campos:

• CIALCECI-REQ-CODE (MEMAEXRC) debe establecerse en CAILCECI-REQ-ENCRYPT (MEMAEBLK).

186


• CIALCECI-DATA-LEN (MEMALDAT) debe establecerse en la longitud de los datos

a ser encriptados. Debe ser mayor que cero y menor que o igual al valor de

CIALCECI-MAX-BLKSIZE (MEMAMAXB), que se estableció durante la solicitud de

inicialización emitida anteriormente.

La solicitud de cifrado de datos también requiere que se pasen otros dos

parámetros en la lista de parámetros:

• El segundo parámetro es la dirección de los datos de entrada a cifrar.

• El tercer parámetro es la dirección del búfer de salida para cifrado datos.

El área del búfer de salida debe asignarse igual a la Tamaño CIALCECI-MAX-

BLKSIZE (MEMAMAXB).

Si la solicitud se completa con éxito, es decir, CIALCECI-RC (MEMARCOD) es igual

a CERO, luego se establece un código de retorno de 2 o 4 en CIALCECI-EXRC

(MEMAEXRC). Estos códigos tienen lo siguiente significados

Código de retorno

Descripción

2 Los datos de la aplicación se almacenaron en el búfer, pero se cifraron por completo. El bloque aún no está disponible para que la aplicación escriba.

4 Los datos de la aplicación fueron almacenados en búfer, y ahora están completamente encriptados bloque está disponible para que la aplicación escriba. El largo del bloque encriptado se configura en CIALCECI-OUTPUT-LEN (MEMALOUT) campo. El búfer de salida pasó como el tercero parámetro de la solicitud de datos cifrados contiene el cifrado bloque de datos para que la aplicación escriba en un disco, cinta u otro dispositivo. El bloque cifrado puede tener un SHA-1 o un SHA-2 hash al final de cada bloque, dependiendo de cifrado utilizado

4. Encrypt Done Una vez que la aplicación ha enviado todos los datos para ser encriptados, debe

hacer una solicitud encriptada No se pasan datos de entrada en esta solicitud, y

es similar a una solicitud de cierre. Para esta solicitud, la aplicación debe

establecer CIALCECI-REQ-CODE (MEMARQST) igual a CAILCECI-REQ-ENCRYPT-

DONE (MEMAEDON). Si la solicitud se completa con éxito, es decir, CIALCECI-RC

(MEMARCOD) es igual a CERO, entonces un código de retorno extendido de 2 o 4

es establecido en CIALCECI-EXRC (MEMAEXRC). Estos códigos tienen los

siguientes significados:

187


Código de retorno

Descripción

2 No hay bloque de datos cifrados para que la aplicación escriba.

4 Hay un bloque de datos cifrado final para la aplicación escribir. El tamaño de este último bloque cifrado es probablemente menor que el valor de CIALCECI-MAX-BLKSIZE (MEMAMAXB). La longitud de este bloque se establece en CIALCECI-OUTPUTLEN (MEMALOUT) campo. El búfer de salida pasó como el tercer parámetro de la solicitud de datos cifrados anterior contiene el último bloque de datos cifrado para que la aplicación escriba un disco, cinta u otro dispositivo.

5. Borrar clave La solicitud de borrar clave borra la clave actual a ceros binarios en la memoria.

Para esta solicitud, la aplicación debe establecer CIALCECI-REQ-CODE

(MEMARQST) igual a CAILCECI-REQ-ERASE-KEY (MEMAXKEY).

6. Release Token La solicitud de token de liberación libera el almacenamiento de token asignado.

Para esto solicitud, la aplicación debe establecer CIALCECI-REQ-CODE

(MEMAEXRC) igual a CAILCECI-REQ-REL-TOKEN (MEMARTOK).

Encryption Flow Los datos se almacenan internamente en función del valor de CIALCECI-

MAXBLKSIZE (MEMAMAXB). CECI agrega un pad de 1 a 15 bytes más un Hash de

32 bytes al final de cada bloque cifrado con un SHA-1, SHA-2, o nulo hash. A

medida que pasa datos para encriptar, se le notifica que El bloque cifrado está

listo para ser escrito.

Esto también es cierto para CIALCECI-REQ-ENCRYPT-DONE (MEMAEDON), que

casi siempre se completa con el último cifrado bloque para que escribas. Todos

los bloques anteriores al último son iguales a CIALCECI-MAX-BLKSIZE

(MEMAMAXB). El último bloque es menos que o igual a este tamaño. Debido a

que CECI almacena los datos en datos cifrados solicitudes, puede haber o no un

búfer parcial de datos cuando se emite una solicitud cifrada. Puede ser que los

últimos datos cifrados la solicitud devuelven un bloque encriptado y no queda

nada después de finalizar solicitud. En ese caso, se establece un código de

retorno de 2 en CIALCECI-EXRC (MEMARCOD).

Por ejemplo, si CIALCECI-MAX-BLKSIZE (MEMAMAXB) está establecido en 4096 y

envía 4063 bytes durante un cifrado, recibiría CIALCECI-EXRC igual a CIALCECI-

RC-HAVE-DATA con el Campo CIALCECI-OUTPUT-LEN igual a 4096. Este bloque,

cuando descifrado, contendría sus 4063 bytes de datos, un pad de un byte con

x01, y luego un área de 32 bytes en el extremo con un SHA-1, SHA-2 o nulo

picadillo. Cuando se descifre, recibirá una longitud de 4063 (relleno y hash

eliminado). En el CIALCECI-REQ-ENCRYPT-DONE (MEMAEDON), recibiría

CIALCECI-EXRC (MEMARCOD) igual a CIALCECI-RC-NO-DATA (MEMAE002).

188


Pseudocódigo descifrado Debe realizar las siguientes solicitudes para implementar el descifrado en un

solicitud:

1. Inicializar solicitud

2. Solicitud de clave de creación

3. Solicitud de descifrado de datos

4. Solicitud de borrado de clave

5. Solicitud de token de lanzamiento

A continuación se detalla información detallada sobre cada paso.

1. Inicializar Para la solicitud de inicialización, la aplicación debe establecer los siguientes

campos:

• CIALCECI-REQ-CODE (MEMAEXRC) debe establecerse en CAILCECI-REQ-INIT (MEMAINIT).

• CIALCECI-MAX-BLKSIZE (MEMAMAXB) debe contener el tamaño máximo de bloque utilizado por el proceso de encriptación la aplicación. Este valor debe ser un múltiplo de 16, y debe ser entre 256 y 65536 (64K).

• CIALCECI-KEY-PHASE (MEMAKYPH) debe contener la fase nombre del cifrado generado y semillas clave.

Una vez completada la inicialización, el área de solicitud contiene la dirección de un token que ha sido asignado. Debe pasar la misma área de solicitud y solo cambie los campos necesarios para una solicitud específica.

2. Crear clave Para la solicitud de creación de clave, la aplicación debe establecer los siguientes campos:

• CIALCECI-REQ-CODE (MEMAEXRC) debe establecerse en CAILCECI-REQ-GEN-KEY (MEMACRKY).

• CIALCECI-CURRENT-CIPHER (MEMACIPH) y CIALCECICURRENT- KEY-NBR (MEMAKNUM) están configurados en el cifrado predeterminado y el número de clave, respectivamente, que se establecieron durante el anterior Inicializar solicitud.

Si estos campos se configuraron con otros valores en la aplicación en el cifrado (en la solicitud de creación de clave), deben establecerse con los mismos valores aquí.

189


3. Descifrar datos Debe descifrar cada bloque por separado para descifrar el anterior datos

encriptados Para la solicitud de descifrar datos, la aplicación debe establecer el

siguientes campos:

• CIALCECI-REQ-CODE (MEMAEXRC) debe establecerse en CAILCECI-REQ-

DECRYPT (MEMADBLK).

• CIALCECI-DATA-LEN (MEMALDAT) debe establecerse en la longitud de ser

descifra el bloque, que debería ser el mismo que el valor de CIALCECI-MAX-

BLKSIZE (MEMAMAXB) utilizado durante el proceso de cifrado (excepto el último

bloque de datos en el archivo).

El segundo parámetro pasado en la lista de parm es la dirección del bloque

cifrado para ser descifrado. El tercer parámetro pasado es el dirección en la que

los datos descifrados se almacenarán una vez que se hayan realizado

correctamente terminación. Este tercer parámetro puede ser el mismo que el

segundo parámetro, en cuyo caso los datos se descifran en su lugar.

Después de una solicitud de descifrado exitosa, la longitud real de los datos

descifrados (menos el pad y el hash) se configura en CIALCECI-OUTPUT-LEN

(MEMALOUT) campo.

4. Borrar clave La solicitud de borrar clave borra la clave actual a ceros binarios en la memoria. Para esta solicitud, la aplicación debe establecer CIALCECI-REQ-CODE (MEMAEXRC) igual a CAILCECI-REQ-ERASE-KEY (MEMAXKEY).

5. Release Token La solicitud de token de liberación libera el almacenamiento de token asignado. Para esto solicitud, la aplicación debe establecer CIALCECI-REQ-CODE (MEMAEXRC) igual a CAILCECI-REQ-REL-TOKEN (MEMARTOK).

CIALSEED JCL Debe editar y ejecutar un JCL CIALSEED para generar una fase y crear definiciones requeridas Estas definiciones se describen a continuación. Cada uno se utiliza en un JCL de muestra que aparece en la siguiente sección.

Definiciones Nombre de fase El JCL CIALSEED genera la fase que une la aplicación debe especificar en la CIALCECI-KEY-PHASE (MEMAKYPH) en el área de solicitud. Un comando PUNCH se usa para define el nombre de la fase.

ADVERTENCIA: Si se elimina la fase definida en CIALSEED JCL, todos los datos cifrados con sus cifras y valores clave serán Perdido permanentemente.

Debe establecer procedimientos apropiados para mantener, recuperando y destruyendo esta fase crítica. Los siguientes escenarios Mostrar la importancia de los buenos procedimientos en la gestión de esta fase.

190


Buen ejemplo: el centro de datos está en un país hostil y debe ser evacuado de

repente. Simplemente elimine esta fase y todos los datos cifrado con la interfaz

CECI es seguro e inutilizable por invasores hostiles. También tiene una copia de

la fase en un lugar seguro, ubicación remota a la que pueden acceder personas

autorizadas.

Mal ejemplo: implementó la API en un entorno de producción y ocurre un

desastre natural que destruye el centro de datos. Sus datos son respaldados y

listos para ser restaurado en un sitio de recuperación de desastres, pero usted

descuidado incluir el código fuente generado por CIALSEED o fase en sus planes

de recuperación ante desastres. Los datos restaurados se cifran y no puede ser

descifrado. Efectivamente, los datos se pierden.

Frases de Seed y números clave. La macro CIALSEED y SEED la instrucción define

tanto una frase inicial clave como un número clave asociado. La palabra clave

PHRASE se puede establecer en cualquier valor alfanumérico hasta 255 bytes de

largo. La palabra clave XPHRAS se puede establecer en cualquier valor binario

(representado en caracteres hexadecimales EBCDIC). Cada frase debe estar

encerrada entre comillas simples Puede definir múltiples frases / números clave.

Número de clave predeterminado. La macro CIALSEED y la palabra clave

DEFLTKY establece el número predeterminado de semilla clave utilizado por las

aplicaciones. Si cambias claves o iniciar una operación de cifrado / descifrado,

debe emitir CAILCECI-REQ-GEN-KEY (MEMACRKY) utilizando un número de clave

definido en la fase generada por CIALSEED.

Cifrado predeterminado La palabra clave DEFLTCI establece el cifrado

predeterminado algoritmo y hash. Las combinaciones de cifrado / hash que

puede seleccionar son enumerado en los comentarios en la muestra JCL. Las

aplicaciones pueden anular esto valor en la solicitud de creación de clave.

Consulte la sección "Selección de suite de cifrado", página 193, para obtener

más información. Al seleccionar una combinación de cifrado / hash.

191


Ejemplo El siguiente JCL es un ejemplo que puede examinar y modificar. los la fase que

genera se llama "SEEDSAMP".

Cadenas que representan las combinaciones de cifrado, hash y modo de cifrado

que puede seleccionar se enumeran en los comentarios de archivo. Por ejemplo,

la primera entrada en la lista es ACNULSH1.

// JOB CIALSEED // OPTION CATAL // LIBDEF *,CATALOG=lib.sublib // EXEC ASMA90,SIZE=ASMA90 PUNCH ' PHASE SEEDSAMP,* ' SEEDSAMP CIALSEED BEGIN,DEFLTKY=1,DEFLTCI=ACA12SH1 * * * Available cipher equates for DEFLTCI= * ACNULSH1 08 NULL-SHA1 (no encrypt) * ACDESNUL 12 SDES-NULL CBC mode * ACDESSH1 16 SDES-SHA1 CBC mode * ACTDENUL 20 TDES-NULL CBC mode * ACTDESH1 24 TDES-SHA1 CBC mode * ACA12NUL 28 AES128-NULL CBC mode * ACA12SH1 32 AES128-SHA1 CBC mode * ACA19NUL 36 AES192-NULL CBC mode * ACA19SH1 40 AES192-SHA1 CBC mode * ACA25NUL 44 AES256-NULL CBC mode * ACA25SH1 48 AES256-SHA1 CBC mode * ACA12SH2 52 AES128-SHA2 CBC mode * ACA19SH2 56 AES192-SHA2 CBC mode * ACA25SH2 60 AES256-SHA2 CBC mode * AEA12SH1 64 AES128-SHA1 ECB mode * AEA19SH1 68 AES192-SHA1 ECB mode * AEA25SH1 72 AES256-SHA1 ECB mode * AEA12SH2 76 AES128-SHA2 ECB mode * AEA19SH2 80 AES192-SHA2 ECB mode * AEA25SH2 84 AES256-SHA2 ECB mode * AEDESNUL 88 SDES-NULL ECB mode * AEDESSH1 92 SDES-SHA1 ECB mode * AETDENUL 96 TDES-NULL ECB mode * AETDESH1 100 TDES-SHA1 ECB mode * CIALSEED SEED,KEY=1, X PHRASE='SEEDSAMP sample key phrase 1' CIALSEED SEED,KEY=2, X PHRASE='SEEDSAMP sample key phrase 2' CIALSEED SEED,KEY=3, X PHRASE='SEEDSAMP sample key phrase 3' CIALSEED SEED,KEY=4, X XPHRAS='04F9C16E02BA6620CB1DE0F6671348C190220AD331CB' CIALSEED SEED,KEY=5, X XPHRAS='D409712E823A2617C011E6F6371548C99112468321BB' CIALSEED END END /* // EXEC LNKEDT,SIZE=512K /* /&

192


Selección de la suite Debe seleccionar un conjunto de cifrado y valores relacionados cuidadosamente: de cifrado

• Elija una fuerza de cifrado que cumpla con sus estándares de auditoría pero lo haga no requiere una sobrecarga excesiva de la CPU. En general, el más fuerte es el cifrado, mayor es la sobrecarga de la CPU.

Seleccionar un cifrado compatible con una asistencia de hardware criptográfico (CPACF) puede reducir en gran medida la sobrecarga de la CPU. El disponible las asistencias de hardware se pueden verificar emitiendo la siguiente z / VSE comando a la partición del servidor de seguridad:

MSG FB,DATA=STATUS=CRYPTO BST223I CURRENT STATUS OF THE SECURITY TRANSACTION SERVER: ADJUNCT PROCESSOR CRYPTO SUBTASK STATUS: AP CRYPTO SUBTASK STARTED .......... : NO CPU CRYPTOGRAPHIC ASSIST FEATURE: CPACF AVAILABLE .................... : YES INSTALLED CPACF FUNCTIONS: DES, TDES-128, TDES-192 AES-128 SHA-1, SHA-256 END OF CPACF STATUS

Los cifrados de bloque disponibles son Data Encryption Standard (DES) y Estándar de cifrado avanzado (AES). AES ha reemplazado DES y es más eficiente y seguro. Para más información sobre criptografía algoritmos, vaya a http://csrc.nist.gov/groups/ST/toolkit/index.html.

• Elija el tipo de hash (SHA o nulo) para usar con el cifrado. El SHA hash agrega algo de sobrecarga de CPU, pero proporciona integridad para el datos encriptados Los cifrados de cifrado en bloque AES y DES proporcionan secreto y confidencialidad de los datos, pero no impiden la los datos encriptados se modifiquen. El hash seguro (SHA) garantiza que los datos cifrados no se hayan modificado.

• Elija el modo operativo para el cifrado de cifrado, ya sea retroalimentación electrónica (BCE) o modo de encadenamiento de bloques cifrados (CBC). En modo ECB, cada bloque se cifra de forma independiente, y cualquier Se puede descifrar el bloque de acceso aleatorio. Pero los bloques que contienen los mismos valores siempre se cifran con los mismos valores exactos. DES usa un Bloque de 8 bytes, y AES usa un bloque de 16 bytes. Entonces, suponiendo que use el cifrado DES en modo ECB, si cifraste un bloque 4K de binario ceros, vería exactamente el mismo patrón de cifrado de 8 bytes para cada bloque de 8 bytes en el área 4K.

El modo CBC aborda el problema de repetir patrones agregando un vector de inicialización para el material clave generado. Este 8 (DES) o el vector 16 (AES) es OR exclusivo con los primeros 8 (DES) o 16 (AES) bloque de datos encriptados. Los bloques siguientes y siguientes son siempre exclusivos O 'd con el bloque cifrado anterior. Esta hace que los datos cifrados sean mucho más seguros de lo que serían en el BCE modo, pero también significa que no puede descifrar aleatoriamente ningún bloque en el expediente. Los bloques encadenados deben descifrarse de principio a fin.

193

http://csrc.nist.gov/groups/ST/toolkit/index.html


Problemas de depuración

Para errores generados por la API SSL, explicaciones breves de la mayoría de los

errores los códigos están contenidos en el miembro SSLVSE.A, que está en el TCP

/ IP Para la biblioteca VSE.

Para depurar errores producidos por la API SSL o la API CryptoVSE, usted puede

crear un $ SOCKDBG.PHASE personalizado para generar el diagnóstico

información. Luego puede enviar esta información al soporte técnico de CSI para

un análisis detallado del problema.

Para habilitar el diagnóstico, use la siguiente configuración de palabras clave de

forma personalizada Fase $ SOCKDBG. Esta fase personalizada debe colocarse en

una prueba lib.sublib que se encuentra antes de la fase predeterminada en la

cadena de búsqueda.

Configuración de palabras clave

Resultado

FL02=$DBGISON Activa el diagnóstico para todos los componentes (para ejemplo, BSD y SSL)

MSGT=$DBGALL Especifica que todas las categorías de mensajes deben ser registrado (por ejemplo, diagnóstico y crítico)

SSLD=$DBGSDMP Crea un volcado de registros de protocolo de enlace SSL / TLS

CIAL=$DBGSDMP Crea un volcado de entrada criptográfica y áreas de salida

Consulte el "Apéndice B: Fase de depuración de $ SOCKDBG", página 203, para

información sobre otras configuraciones de palabras clave y los pasos para

modificar esta fase. Este apéndice también contiene un ejemplo de un $

SOCKDBG modificado fase.

194


Notas de programación

Las siguientes notas se aplican al desarrollar SSL / TLS habilitado aplicaciones:

• Los programas deben incluir el mazo IPCRYPTS.OBJ en su edición de enlace JCL

Este es un pequeño programa de código auxiliar que carga la fase IPCRYPTO a

procesar la solicitud Cuando hay nuevo mantenimiento disponible, usted no Hay

que vincular editar la aplicación de usuario nuevamente.

• El estándar de enlace del lenguaje C se utiliza para pasar todos los parámetros.

• Cuando se llama a la función desde un programa Assembler, el La lista de

parámetros es siempre una lista de direcciones. El bit de orden superior de la El

último parámetro de la lista debe estar activado para indicar el final de lista de

parámetros

• Si un parámetro es un tipo de dirección, la dirección se almacena directamente

en la lista de parámetros.

• Si el parámetro es un parámetro de tipo de valor, la dirección del valor es

almacenado en la lista de parámetros.

• Todas las direcciones aprobadas se validan para garantizar que estén dentro de

la partición de almacenamiento desde la cual se emite la solicitud. Los siguientes

archivos son usados:

SSLVSE.H Archivo de encabezado para programas de lenguaje C / C ++.

SSLVSE.A Archivo de macro para programas BAL (ensamblador).

• El código de muestra está disponible en CSI en www.csi-international.com.

195


Apéndice A:

Fase de opciones de $ SOCKOPT

Usando $SOCKOPT Las interfaces BSD y SSL / TLS en TCP / IP PARA VSE utilizan el conjunto de

opciones por la fase de opciones de $ SOCKOPT. El $ SOCKOPT.PHASE es

CDLOADed en la partición usando estas interfaces en tiempo de ejecución, y el

fase se puede personalizar para permitir valores específicos de instalación. El

valor por defecto los valores deberían ser suficientes para la mayoría de las

instalaciones y el soporte técnico de CSI debe ser consultado antes de

cambiarlos. Ejemplos en este apéndice muestra cómo se pueden definir nuevos

valores. Las opciones para el zócalo BSD La interfaz y la interfaz SSL / TLS se

describen en tablas separadas.

La fase $ SOCKOPT se carga en función de la LIBDEF de la partición cargándolo

Esto significa que si tiene varias copias de la fase, el primero que se encuentra en

la cadena LIBDEF de una partición es el que se usa para ese dividir. En general,

debe instalar solo una copia de la fase.

Fase predeterminada El siguiente trabajo de muestra crea una fase de opciones con el valor

predeterminado actual ajustes Esta muestra se puede modificar para crear una

costumbre $ SOCKOPT.PHASE.

196

Appendix A: $SOCKOPT Options Phase

// JOB $SOCKOPT // OPTION CATAL // LIBDEF *,SEARCH=lib.sublib // LIBDEF *,CATALOG=lib.sublib // EXEC ASMA90,SIZE=ASMA90,PARM='SZ(MAX-200K,ABOVE)' PUNCH ' PHASE $SOCKOPT,* ' $SOCKOPT CSECT SOCKOPT CSECT, Generate a csect X SYSID=00, TCP/IP sysid when BSDCFG1 contains $OPTUSYD X BSDCFG1=$OPTMECB+$OPTSNWT+$OPTNBSD, Options flag 1 X BSDCFG2=$OPTGTSP+$OPTCHKR, X BSDXPHS=IPNRBSDC, Name of BSD phase X CHKT=60, Check sockets seconds X CLST=30, Close timeout seconds X CSRT=30, Socket reuse seconds X QUEDMAX=0, Max queued connects allowed X RCVT=00, Receive timeout seconds X SNOWMAX=262144, 256K max for send nowait X SOCFLG1=00, Socket flag special options X SSLCIPH=A, SSL default cipher suites X SSLFLG1=00, SSL option flag 1 X SSLFLG2=00, SSL option flag 2 X SSLSTOR=80 SSL cached sessions END $SOCKOPT /* // EXEC LNKEDT,SIZE=512K /* /&

Ejemplo 1: configuración de El siguiente procedimiento muestra cómo anular ambos valores Stack ID predeterminados del sistema ID de pila y el ID establecido por la instrucción // OPTION SYSPARM = en un programa JCL.

1. Copie y pegue el trabajo de muestra anterior en su editor local.

2. Modifique la siguiente configuración de palabras clave:

Palabra clave Editar la configuración para ...

BSDCFG1 Incluye $ OPTUSYD (opciones separadas con un '+')

SYSID Especifique una ID de pila TCP / IP PARA VSE

3. Modifique el parámetro CATALOG para que contenga un lib.sublib en la fase cadena de búsqueda de la partición en la que se ejecuta la aplicación BSD.

4. Ejecute el trabajo modificado para crear el $ SOCKOPT.PHASE personalizado.

5. Realice un ciclo de la partición en la que se encuentra la aplicación (por ejemplo, CICS) ejecutándose para forzar una recarga del $ SOCKOPT.PHASE recién creado.

197


Ejemplo 2: configuración Este ejemplo muestra cómo cambiar el conjunto de cifrado predeterminado de de Default Cipher Suite utilizado por Aplicaciones SSL / TLS como SecureFTP. El conjunto de cifrado se configura durante la llamada gsk_secure_soc_init () de la aplicación con v3cipher_specs parámetro. Si la aplicación SSL / TLS establece este parámetro en cero, entonces permite que el sistema use el conjunto de cifrado p predeterminado.

Use el siguiente procedimiento para anular el conjunto de cifrado predeterminado.

1. Copie y pegue el trabajo de muestra en su editor local.

2. Reemplace la configuración SSLCIPH con una de las siguientes selecciones:

Selección de cifrado

Descripción

SSLCIPH=A Utilice todas las suites de cifrado posibles SSLCIPH=D1 Utilice solo conjuntos de cifrado DES

SSLCIPH=E1 Utilice solo conjuntos de cifrado AES SSLCIPH=N1 Utilice solo suites de cifrado nulo SSLCIPH=W Utilice solo conjuntos de cifrado débiles SSLCIPH=M Utilice solo suites de cifrado medianas

SSLCIPH=S Utilice solo conjuntos de cifrado fuertes SSLCIPH=H1 Utilice solo suites asistidas por hardware

1 No se aplica a TLS 1.2. Consulte "Nuevas configuraciones de $ SOCKOPT para TLS 1.2 ”en la página 201.

3. Modifique el parámetro CATALOG para que contenga un lib.sublib en la fase cadena de búsqueda de la partición en la que la aplicación SSL / TLS se ejecuta

4. Ejecute el trabajo modificado para crear el $ SOCKOPT.PHASE personalizado.

5. Realice un ciclo de la partición en la que se encuentra la aplicación (por ejemplo, CICS) ejecutándose para forzar una recarga del $ SOCKOPT.PHASE recién creado.

Tenga en cuenta que algunas aplicaciones están configuradas para configurar el conjunto de cifrado para ser utilizado. Si están haciendo esto, entonces el valor no puede ser anulado por modificando la $ SOCKOPT.PHASE. Consulte con el proveedor de la aplicación para verificar cómo se configura el conjunto de cifrado. Esto se aplica cuando el SSL30, se utiliza TLS 1.0 o la versión del protocolo TLS 1.1.

Nota: Cuando se utiliza la versión del protocolo TLS 1.2, puede anular el conjunto de cifrado predeterminado de la aplicación incluso cuando el campo SIN @ V3CS no está puesto a cero. Para hacer esto, use la opción SSLFLG1 = $ OPTCIPH ajuste. Consulte “Opciones de interfaz SSL / TLS” en la página 201.

198


Opciones de interfaz BSD La siguiente tabla enumera la configuración de opciones para la interfaz BSD. Las

opciones para las palabras clave BSDCFG1 y BSDCFG2 pueden ser concatenado

utilizando un carácter "+".

Función Configuración de opciones

Descripción

Automático socket limpiar

BSDCFG2=$OPTCHKR CHKT=60

Establecer estas opciones hace que se desconecte pero socket no cerrados (muertos) para ser detectados y hechos Disponible para reutilizar. CHKT = 60 especifica un intervalo nominal de comprobación de socket de 60 segundos. El zócalo se marca cerrado si la conexión ha sido terminada. Puede ser reutilizado después del Intervalo CSRT.

Enlazar BSDCFG1=$OPTBNDX Haga que Bind verifique las particiones externas. Por defecto, comprobaciones de enlace para un puerto ya vinculado dentro de solo la partición de la aplicación. Esta opción provoca enlazar para verificar también todas las otras particiones para un puerto ya atado a un enchufe.

Cerrar BSDCFG1=$OPTCNFW Cerrar sin FIN esperar de extranjeros la conexión de la aplicación finaliza inmediatamente después cerca. La pila TCP / IP envía una solicitud de cierre (FIN) pero descarta cualquier datagrama entrante. Eso no espera una FIN del extranjero conexión.

CSRT=30 Un socket que está cerrado desde un aborto, cierre o la limpieza automática está disponible para su reutilización después del número de segundos especificado.

Givesocket/ Takesocket

BSDCFG2=$OPTGTSP Esta opción causa givesocket / takesocket procesamiento que se produce en la misma partición que el solicitud, no en la partición TCP / IP FOR VSE. Esto mejora el rendimiento de las aplicaciones que usan una transacción de escucha para pasar conexiones a otras tareas.

199



Descripción

Escucha QUEDMAX=qmax QUEDMAX = qmax afecta la conexión profundidad de la cola para aplicaciones que usan BSD interfaz de socket. Si qmax = 0 (el valor predeterminado), el PORTQUEUE El comando se puede utilizar para controlar el número de solicitudes de conexión para ser aceptadas y puestas en cola. Si qmax> 0, una aplicación puede especificar un recuento de profundidad de cola en listen (), pero si el valor de la aplicación excede QUEDMAX, el No se utilizará el valor de la aplicación. Ver el función listen (), página 37, y "Port Queuing" en el capítulo "Rendimiento" en TCP / IP FOR Guía de instalación de VSE para más detalles.

SOCFLG1=$OPTDNSQ SOCFLG1 = $ OPTDNSQ desactiva la cola de conexiones entrantes cuando el servidor no está en un escuchar estado Esto significa que tanto el QUEDMAX = valor y el valor de la aplicación será ignorado y nuevas conexiones entrantes será rechazado hasta que el servidor vuelva a ingresar escuchar estado

Recibir BSDCFG1=$OPTXNBK Extienda sin bloqueo a todas las llamadas. En anteriores libera una llamada de recepción podría bloquear incluso en un socket sin bloqueo. Esta opción extiende el sin bloqueo para recibir llamadas. Un bloque de agua el error número 1102 puede ocurrir durante una recepción con esta opción de configuración.

Selectex BSDCFG1=$OPTMECB Permitir BCE de múltiples usuarios en selectex. Esto es el sexto parámetro pasó a una llamada selectex. Sin esta opción, el sexto parámetro es considerado una sola dirección del BCE.

Enviar BSDCFG1=$OPTSNWT SNOWMAX=262144

Establecer estas opciones permite hasta 256K de datos no reconocidos que se enviarán antes de esperar para un reconocimiento Cuando un CIERRE es emitido, todos los datos se reconocen antes de CERRAR completa.

ID del sistema BSDCFG1=$OPTUSYD SYSID={id}

Establecer estas opciones anula la pila predeterminada Identificación con identificación. Consulte "Ejemplo 1: Configuración de la pila ID ", página 197.

200


Interfaz SSL/TLS La siguiente tabla enumera la configuración de opciones para la interfaz SSL / Opciones TLS. La configuración de las palabras clave SSLFLG1 y SSLFLG2 se puede concatenar usando un carácter "+".


Descripción

Conjunto de cifrado Nota: para TLS 1.2, ver Texto abajo.

SSLCIPH={A|D|E|N|W |M|S|H}

Reemplazar el conjunto de cifrado predeterminado utilizado por Aplicaciones SSL / TLS. Consulte "Ejemplo 2: Configuración el conjunto de cifrado predeterminado ", página 198, para un descripción de cada carta de selección de suite.

SSLFLG1=$OPTCIPH Cuando se usa TLS 1.2, forzar una anulación de configuración de la suite de cifrado de la aplicación y use el SSLCIPH = configuración. Vea el texto a continuación para más detalles.

Cerrar SSLFLG1=$OPTSRQC Requerir alerta close_notify. Ver el Función gsk_secure_soc_close () en la página 134.

Hardware ayudar Nota: estos ajustes hacen no se aplica a TLS 1.2; ver Texto abajo.

SSLFLG2=$OPTSNHC No use criptografía de hardware para RSA operaciones

SSLFLG2=$OPTSNZA Nunca emita la función criptográfica CP Assist (CPACF) instrucciones de hardware z / architecture.

SSLFLG2=$OPTSFZA Emita siempre el hardware CPACF z / architecture instrucciones. Consulte también "Configuración de opciones de asistencia de hardware" en página 125.

Inicializar SSLFLG1=$OPTSNFR Currículum rápido no permitido. Ver "Notas de uso" en gsk_secure_soc_init (), página 141.

SSLFLG1=$OPTTLSX Solo permita que se negocie TLS 1.2 durante Inicialización de sesión.

SSLSTOR=80 El número máximo de sesiones almacenadas en caché para una aplicación de servidor SSL / TLS. Un valor de 80 cachés un máximo de 80 sesiones SSL / TLS que luego pueden ser reutilizados por clientes extranjeros que usar currículum rápido. Usar un valor de 0 es equivalente a establecer SSLFLG1 = $ OPTSNFR. Cada sesión en caché requiere aproximadamente 64K de almacenamiento de 31 bits.

Nuevo $SOCKOPT Se puede crear un $ SOCKOPT.PHASE personalizado para controlar el Configuraciones para TLS 1.2 comportamiento de Los protocolos SSL / TLS. Se carga en CD en la partición en la que la aplicación se está ejecutando y, por lo tanto, debe catalogarse en una lib.sublib en la cadena de búsqueda de la fase libdef de la aplicación.

Los cambios en la configuración de $ SOCKOPT para el protocolo TLS 1.2 son los siguientes.

201


• De forma predeterminada, se permite que las versiones anteriores del

protocolo SSL / TLS sean usado.

El uso de SSLFLG1 con la configuración $ OPTTLSX solo permite TLS 1.2 a

negociarse durante la inicialización de la sesión: versiones anteriores del

protocolo no está permitido.

• De manera predeterminada, las aplicaciones configuran los conjuntos de

cifrado que usan con Puntero SIN @ V3CS durante la inicialización de la sesión. Si

este campo es cero, entonces se usa la configuración SSLCIPH =. El valor

predeterminado es SSLCIPH = A, que permite utilizar todas las suites de cifrado

compatibles.

Para TLS 1.2, la opción SSLCIPH permite la siguiente configuración:

-A es el valor predeterminado y permite utilizar todas las suites de

cifrado compatibles.

-S solo permite el uso de conjuntos de cifrado fuertes.

-M solo permite el uso de conjuntos de cifrado medios.

-W solo permite el uso de conjuntos de cifrado débiles.

Además, puede anular los conjuntos de cifrado de la aplicación configurando

SSLFLG1 con $ OPTCIPH. Con $ OPTCIPH, la configuración SSLCIPH anulará la

configuración de la aplicación incluso cuando su campo SIN @ V3CS no es cero

• Cuando se negocia la versión del protocolo TLS 1.2, el hardware ayuda tanto

para RSA como para CPACF deben estar disponibles, y el SSLFLG2 la

configuración ($ OPTSNHC, $ OPTSNZA o $ OPTSFZA) se ignora.

Consulte también "Apéndice C: Mejora de TLS 1.2".

202

Appendix B: $SOCKDBG Debugging Phase

Usando $SOCKDBG Puede depurar y diagnosticar problemas en BSD y SSL / TLS aplicaciones creando

una fase personalizada $ SOCKDBG. Puedes seleccionar la información de

diagnóstico que desea generar editando un trabajo que cataloga esta fase. La

información incluye mensajes que pueden ser emitidos a SYSLOG o SYSLST y

volcados de parámetros y control bloques Estos mensajes y vuelcos pueden ser

solicitados por técnicos de CSI soporte, al que puede contactar si necesita ayuda

para interpretar la información.

Muestra Job El siguiente trabajo de muestra contiene la configuración predeterminada actual.

Usted puede modifique este trabajo para crear un $ SOCKDBG.PHASE

personalizado. El siguiente Las secciones explican cómo editar y ejecutar este

trabajo para generar diagnósticos.

// JOB $SOCKDBG // OPTION CATAL // LIBDEF *,CATALOG=lib.sublib // EXEC ASMA90,SIZE=ASMA90 PUNCH ' PHASE $SOCKDBG,* ' SOCKDBG CSECT, Generate BSD SSL/TLS debugging phase X FL01=$DBGWLST+$DBGWLOG, Messages to syslst and syslog X FL02=$DBGISON, Debug flag is on X FL03=$DBGIOFF, Connection diagnostics are off X MSGT=$DBGVITA+$DBGCRIT+$DBGIMPO+$DBGRESP, Message Types X DUMP=$DBGNONE, Diagnostic dumps $DBGNONE or $DBGSDMP X LSTCCW=09, CCW write command for syslst X SSLD=$DBGNONE, Diagnostics for SSL api parameters X CIAL=$DBGNONE Diagnostic dumps for Crypto functions/* // EXEC LNKEDT,SIZE=512K /* /&

203


Configuraciones Keyword La siguiente configuración de palabras clave controla los mensajes y los volcados.

• Enrutamiento de mensajes. La palabra clave FL01 controla el enrutamiento de mensajes:

Configuración FL01 Resultado

$ DBGWLST Escribe mensajes en la impresora asignada (SYSLST) para la partición en la que se ejecuta la aplicación

$ DBGWLOG Escribe mensajes en la consola del sistema VSE

$ DBGUPER Escribe mensajes en mayúsculas solamente

Nota: Use $ DBGWLOG con precaución. Puede aumentar el tráfico a la Consola del sistema VSE cuando MSGT = $ DBGALL (ver más abajo) y lento reducir el rendimiento de la aplicación asociada. $ DBGWLST es recomendado y es más eficiente para aplicaciones de alto volumen.

• Código de operación SYSLST CCW. La palabra clave LSTCCW establece el Código de operación CCW que se utilizará para escribir mensajes en SYSLST. El valor predeterminado es 09 para escribir y luego espaciar una línea. LSTCCW = 0B puede ser especificado para espaciar una línea y luego escribir el mensaje. Esta opción puede evitar superposiciones de impresión en algunas aplicaciones.

• Fuente del mensaje. La palabra clave FL02 especifica el origen del mensaje:

Ajuste FL02 Resultado

$ DBGISBS Habilita mensajes solo para la interfaz BSD

$ DBGISON Habilita mensajes para todos los componentes: BSD, SSL / TLS, etc.

$ DBGISSL Habilita mensajes para los componentes SSL / TLS solamente

$ DBGISCI Habilita mensajes para el criptográfico solo componente

$ DBGIOFF Deshabilita la depuración para todos los componentes

• Tipo de mensaje. La palabra clave MSGT especifica los tipos de mensaje:

Ajuste MSGT Tipo de mensaje

$DBGALL Todos

$DBGCRIT Critico

$DBGVITA Vital

$DBGWARN Advertencia

$DBGIMPO Importante

204


Ajuste MSGT Tipo de mensaje

$DBGINFO Informativo

$DBGRESP Respuesta

$DBGDIAG Debug/diagnostico

$DBGSCTY Relacionados con la seguridad

Consulte el capítulo 10, "Operación", en la instalación de TCP / IP PARA VSE Guía para obtener más información sobre estos tipos de mensajes.

• Indicador de diagnóstico. La palabra clave FL03 controla el diagnóstico de conexión:

Ajuste FL03 Resultado

$DBGDTCP Activa el diagnóstico de conexión para conexiones El diagnóstico adicional la información se envía a SYSLST de TCP / IP.

• Descargas de diagnóstico. La siguiente configuración crea volcados de diagnóstico:

Palabra clave Ajustes de resultado

DUMP=$DBGSDMP Crea volcados usando el servicio SDUMP para aplicaciones que

usan BSD Interfaz de programación de aplicaciones

CIAL=$DBGSDMP Crea volcados usando el servicio SDUMP para aplicaciones que usan la criptografía Interfaz de programación de aplicaciones

SSLD=$DBGSDMP Crea volcados usando el servicio SDUMP para aplicaciones que usan SSL / TLS Interfaz de programación de aplicaciones

SSLD=$DBGSSLD Crear volcados de los parámetros pasados a la programación de aplicaciones SSL / TLS interfaz. Esta es la lista estándar de Parm valores señalados por R1 cuando solicita un Servicio SSL / TLS.

Nota: Por defecto, los SDUMP van al volcado definido lib.subib en la partición en la que se ejecuta la aplicación asociada. También se pierde el encabezado SDUMP que identifica el contenido del volcado. Por lo tanto, siempre envíe los SDUMP a SYSLST. Para forzar SDUMPs directamente a SYSLST y preservar los encabezados, agregue esta declaración JCL:

// OPTION NOSYSDMP

Esta declaración es obligatoria si planea enviar SDUMP a CSI Soporte técnico porque los encabezados SDUMP son críticos importantes para identificar los contenidos descargados.

Appendix B: $SOCKDBG Debugging Phase 205

Ejemplo 1: BSD Tienes una aplicación BSD de prueba. Quieres ver el flujo de todas las funciones Salida de la aplicación utilizadas, pero no desea enviar mensajes al sistema VSE consola. Los mensajes deben ir solo a SYSLST.

Use el siguiente procedimiento.



Palabras clave uso de esta configuración Resultado

FL01 FL01=$DBGWLST Envía mensajes solo a SYSLST

MSGT MSGT=$DBGALL Permite que se emitan todos los mensajes

3. Modifique el parámetro CATALOG para que contenga una prueba lib.sublib en el cadena de búsqueda de fase de la partición en la que se ejecuta la aplicación. La prueba lib.sublib debe ubicarse en la cadena de búsqueda antes de Instalación de TCP / IP FOR VSE lib.sublib y PRD1.BASE, que puede contener la versión distribuida por IBM de $ SOCKDBG. 4. Ejecute el trabajo modificado para crear el $ SOCKDBG.PHASE personalizado. 5. Realice un ciclo de la partición en la que se ejecuta la aplicación, como CICS para forzar una recarga del $ SOCKDBG.PHASE recién creado.

Ejemplo 2: SSL/TLS Tiene una aplicación SSL / TLS suministrada por el proveedor y un servicio Salida de la aplicación técnico CSI el soporte ha solicitado que envíe volcados de diagnóstico y mensajes a SYSLST.

Use el siguiente procedimiento.



Palabras clave uso de esta configuración Resultado

FL01 FL01=$DBGWLST Envía mensajes solo a SYSLST

MSGT MSGT=$DBGALL Permite que se emitan todos los mensajes

SSLD SSLD=$DBGSDMP Habilita los volcados de diagnóstico SSL

3. Modifique el parámetro CATALOG para que contenga una prueba lib.sublib en el cadena de búsqueda de fase de la partición en la que se ejecuta la aplicación. La prueba lib.sublib debe ubicarse en la cadena de búsqueda antes de Instalación de TCP / IP PARA VSE lib.sublib y PRD1.BASE, que pueden contiene la versión distribuida por IBM de $ SOCKDBG.

4. Ejecute el trabajo modificado para crear el $ SOCKDBG.PHASE personalizado.

Appendix B: $SOCKDBG Debugging Phase 206

5. Realice un ciclo de la partición en la que se ejecuta la aplicación para forzar un recarga del $ SOCKDBG.PHASE recién creado.

Notas adicionales:

• La macro SDUMPX se usa para crear los volcados de diagnóstico.

• El JCL de la aplicación debe incluir una entrada // OPTION NOSYSDMP para forzar un volcado a SYSLST en lugar de la biblioteca de volcado predeterminada.

Controlando $SOCKDBG Puede utilizar el comando de consola IBM z / VSE EZAAPI para activar Mensajes $ Mensajes SOCKDBG activados y desactivados dinámicamente. Para aplicaciones CICS, Este comando le permite habilitar y deshabilitar los mensajes de depuración sin ciclismo CICS. Tenga en cuenta que no puede usar este comando para controlar vuelcos en la fase de depuración.

El recurso de rastreo EZAAPI genera uno o más mensajes de rastreo para cada llamada de socket EZASMI o EZASOKET (IBM). Te permite rastrear estas llamadas para todas las particiones en el sistema o para particiones seleccionadas y / o clases dinámicas. Puede dirigir los mensajes de rastreo a SYSLOG o SYSLST.

El comando EZAAPI tiene los siguientes argumentos:

Argumento Descripción

? Mostrar la sintaxis del comando

TRACE Mostrar la configuración de rastreo actual

TRACE=ON Definir e iniciar o reanudar el inicio: • (predeterminado sin rastro definido todavía): defina e inicie un rastro con los valores predeterminados ALL y SYSLST

• (predeterminado después de EZAAPI TRACE = OFF): Reanudar rastro

• Todos: defina e inicie un rastreo para todas las particiones

• PARTE = (parte, ..): defina e inicie un rastreo para el seleccionado particiones

• CLASS = (class, ..): define e inicia un rastreo para clases dinámicas seleccionadas

TRACE=OFF suspender la traza actual

TRACE=END Finalice el rastreo y borre todas las definiciones de rastreo

SYSLST Enviar salida de rastreo a SYSLST (si se asigna SYSLST)

SYSLOG Enviar salida de rastreo a SYSLOG

LOGLST Enviar salida de rastreo a SYSLOG y SYSLST

Consulte la documentación adecuada de IBM z / VSE para obtener más información.

207

Appendix C: TLS 1.2 Enhancement

Visión general TLS 1.2 fue una revisión importante en la evolución de la capa de sockets seguros (SSL) y los protocolos de Seguridad de la capa de transporte (TLS). Está documentado en IETF RFC5246. Debido a que los cambios en TLS 1.2 son significativos, soporte para TLS 1.2 está en nuevos módulos separados. Esto es para proporcionar el máximo estabilidad para aplicaciones que actualmente usan SSL 3.0, TLS 1.0 y TLS 1.1. No se requiere que las aplicaciones realicen ningún cambio y funcionarán sin cambios.

El soporte para TLS 1.2 se puede obtener configurando INI @ PROT de llame a IPCRINIT a PROT0303, que es el valor de liberación interno de TLS para TLS 1.2. Esto hará que las llamadas actuales invoquen los módulos para TLS 1.2.

Using TLS 1.2 Las aplicaciones SSL / TLS VSE que desean admitir solo TLS 1.2 pueden

• Incluya una nueva plataforma de objeto auxiliar, IPCRTLSS.OBJ, para obtener soporte para solo TLS 1.2, y

• Establezca una opción en $ SOCKOPT para permitir solo el uso de TLS 1.2. Ver “Nuevas configuraciones de $ SOCKOPT para TLS 1.2” en la página 201 para más detalles.

Es posible que solo sea compatible con TLS 1.2 cuando desee crear más aplicaciones seguras al no permitir las versiones más antiguas y menos seguras de protocolo a utilizar.

La implementación de TLS 1.2 también requiere que los clientes externos y los servidores le brindan soporte. Pero muchas aplicaciones, como las versiones anteriores de navegadores web, clientes FTP, servidores FTP y clientes TN3270, no pueden proporcionar soporte para TLS 1.2 todavía, y está fuera del control de Clientes y servidores z / VSE que requieren este nuevo nivel de seguridad más alto. Cuando una empresa requiere el uso de TLS 1.2, los proveedores externos deben ser contactados para proporcionar soporte para TLS 1.2.

208


Puntos de entrada Por defecto, los puntos de entrada más antiguos (IPCR *) pasarán

automáticamente el control a los nuevos módulos TLS 1.2, pero puede ser más

eficiente llamar directamente los nuevos puntos de entrada TLS 1.2 que se

resuelven en el nuevo IPCRTLSS.OBJ módulo. La nueva macro TLSVSE.A también

debe ser se usa para generar el soporte para aplicaciones que desean soportar

TLS 1.2. Consulte “Configuración de macros TLSVSE”, página 211, para obtener

detalles sobre macros.

Se deben utilizar nuevos puntos de entrada para invocar el uso de TLS 1.2. Los

puntos de entrada se enumeran en la tabla a continuación. Ellos usan la misma

entrada parámetros documentados para cada función en "Capa de sockets

seguros (SSL) y API de seguridad de la capa de transporte (TLS) ", página 125.

Función C Nombre del punto de entrada

Nuevo Antiguo gsk_initialize() TLSRINIT IPCRINIT gsk_secure_soc_init() TLSRSINI IPCRSINI gsk_secure_soc_read() TLSRSRED IPCRSRED gsk_secure_soc_write() TLSRSWRT IPCRSWRT gsk_secure_soc_close() TLSRSCLS IPCRSCLS gsk_secure_soc_reset() TLSRSRSM IPCRSRST1 gsk_user_set() TLSRUSET IPCRUSET gsk_free_memory() TLSRFMEM IPCRFMEM gsk_get_cipher_info() TLSRGCIN IPCRFMEM gsk_get_dn_by_label() TLSRGDBL IPCRGDBL gsk_uninitialize() TLSRUNIN IPCRUNIN 1 Reanuda una sesión previamente negociada.

Apoyo para mayores Las aplicaciones que llamen a los nuevos puntos de entrada también podrán Versiones de protocolo proporcionar soporte para las versiones anteriores (SSL 3.0, TLS 1.0 y TLS 1.1) desde el código pasará automáticamente el control al IPCRYPTO.PHASE anterior durante la negociación de la sesión SSL / TLS. Aplicaciones usando el nuevo los puntos de entrada anteriores también deben eliminar el IPCRYPTS.OBJ de su editar enlace.

La consideración importante es garantizar la integridad y seguridad de

conexiones, ya que las versiones anteriores del protocolo pueden ser

susceptibles a diversas formas de ataque, como retrocesos y otras debilidades.

Por información más detallada sobre la seguridad de las versiones de protocolo

anteriores, ver https://en.wikipedia.org/wiki/Transport_Layer_Security#Security.

Las búsquedas de Google y otros sitios web también pueden ser referenciados

para más información sobre las exposiciones de seguridad en las versiones

anteriores de SSL y TLS.

209


La pregunta no es tanto "¿Es segura o no la conexión?", Sino más de "¿Qué tan seguro es?" Algunas de las versiones anteriores y cifrado algoritmos como DES ya no se consideran fuertemente asegurados, pero También tenga en cuenta que actualmente muchos clientes y servidores no han sido actualizado para admitir los nuevos algoritmos más seguros, como AES y TLS 1.2. Pero esto debería cambiar con el tiempo.

Cipher Suite Valores

Introducción Los protocolos SSL y TLS permiten a un cliente proponer una lista de cifrado suites que se utilizarán durante la negociación de la sesión, y el servidor luego selecciona el conjunto de cifrado que se utilizará en función de la lista propuesta del cliente. Si no el conjunto de cifrado es aceptable para el servidor, la sesión NO será establecida. La mayoría de las aplicaciones quieren usar el cifrado más fuerte disponible suites, pero esto en general utilizará más gastos generales (tiempo de procesamiento de la CPU).

Además, los conjuntos de cifrado más antiguos pueden quedar obsoletos debido a conocidos debilidades siendo explotadas. TLS 1.2 recomienda no usar más el Algoritmo DES y TCP / IP FOR VSE no lo admite cuando se usa TLS 1.2. Los conjuntos de cifrado más antiguos para SSL 3.0, TLS 1.0 y TLS 1.1, como documentado en la Guía de funciones opcionales, todavía se puede usar cuando se usa Las versiones anteriores del protocolo.

Cuando se usa TLS 1.2, los conjuntos de cifrado que admiten el algoritmo DES tienen ha sido eliminado La compatibilidad con TLS 1.2 también requiere el CP de hardware de IBM Asistencia para la función de función criptográfica (CPACF) para el SHA160, Algoritmos SHA-256, AES128 y AES256.

Cipher Suites TCP / IP FOR VSE actualmente admite estos conjuntos de cifrado para TLS 1.2: para TLS 1.2

• Todas las suites de cifrado

x2F = RSA_AES128CBC_SHA160 x35 = RSA_AES256CBC_SHA160 x3C = RSA_AES128CBC_SHA256 x3D = RSA_AES256CBC_SHA256

• Conjuntos de cifrado fuertes

x3D = RSA_AES256CBC_SHA256

• suites de cifrado medio

x35 = RSA_AES256CBC_SHA160 x3C = RSA_AES128CBC_SHA256

• Suites de cifrado débiles

x2F = RSA_AES128CBC_SHA160

Tenga en cuenta que cuando un cliente propone una lista de suites de cifrado, las suites están en orden preferida del cliente.

210


Selección de Suite Los siguientes casos asumen que un servidor está configurado para usar el Ejemplo "Cifrado completo suites "arriba: 2F, 35, 3C, 3D.

Caso 1. Si el cliente propone (0A 3C 2F 3D), el servidor elegirá el primer partido, que es 3C. Caso 2. Si el cliente propone (0A 2F 3C 3D), el servidor elegirá el primer partido, que es 2F. Tenga en cuenta también que 0A es un conjunto de cifrado basado en DES más antiguo que no es compatible con TLS 1.2.

Pseudo Random Facility Las especificaciones del protocolo TLS 1.2 se definen en IETF RFC5246, que ha (PRF) reemplazado el MD5 / SHA-1 PRF con el conjunto de cifrado especificado PRFs.

Todos los conjuntos de cifrado en este documento usan P_SHA256 como se define en RFC5246, que puede y debe referenciarse para obtener detalles sobre esta central, Función crítica del protocolo.

Configuración de macro Los operandos y valores para la nueva macro TLSVSE se enumeran a TLSVSE continuación.

• TLSVSE GENVTLS – generara: o IPCRTLSS DC CL8'IPCRTLSS' o DC V(IPCRTLSS)

Nota de uso: esto debe usarse para aplicaciones que solo deseen admitir TLS 1.2.

• TLSVSE GENVWTLS – generara: o IPCRTLSS DC CL8'IPCRTLSS' o DC V(IPCRTLSS) o WXTRN IPCRYPTS Older stub

Nota de uso: lo anterior agrega una referencia externa débil (WXTRN) para IPCRYPTS.OBJ. Esto se puede usar para permitir opcionalmente aplicaciones para soportar TLS 1.2 y las versiones anteriores del protocolo.

• TLSVSE GENTLS12 – generara: o SUITETAB DS 0F o SUIT002F DC CL16'RSA_AES128_SH160',XL2'002F',CL2'2F' o SUIT0035 DC CL16'RSA_AES256_SH160',XL2'0035',CL2'35' o SUIT003C DC CL16'RSA_AES128_SH256',XL2'003C',CL2'3C' o SUIT003D DC CL16'RSA_AES256_SH256',XL2'003D',CL2'3D' o SUITENTL EQU 20 Length of a single tab entry o SUITECNT EQU (*-SUITETAB)/SUITENTL Number of entries in table o * o PROTTABL DS 0F o PROT0303 DC XL2'0303',CL5'TLS12',XL1'00' TLS 1.2 defined in RFC5246 o PROTENTL EQU 8 Length of a single tab entry o PROTECNT EQU (*-PROTTABL)/PROTENTL Number of entries in table Nota de uso: lo anterior son las suites de cifrado y la versión de protocolo para compatible solo con TLS 1.2.

211

Appendix C: TLS 1.2 Enhancement • TLSVSE GENVCON – generara: o IPCRYPTS DC CL8'IPCRYPTS' o DC V(IPCRYPTS) Nota de uso: lo anterior se puede utilizar para aplicaciones que requieren soporte para Las versiones

anteriores del protocolo (SSL 3.0, TLS 1.0, TLS 1.1).

• TLSVSE GENSUIT – generara: o SUITETAB DS 0F o SUIT0000 DC CL16'NULL_NULL_NULL ',XL2'0000',CL2'00' o SUIT0001 DC CL16'RSA_NULL_MD5 ',XL2'0001',CL2'01' o SUIT0002 DC CL16'RSA_NULL_SHA ',XL2'0002',CL2'02' o SUIT0008 DC CL16'RSA_SDES040_SHA ',XL2'0008',CL2'08' o SUIT0009 DC CL16'RSA_SDES056_SHA ',XL2'0009',CL2'09' o SUIT000A DC CL16'RSA_TDES168_SHA ',XL2'000A',CL2'0A' o SUIT002F DC CL16'RSA_AES128_SHA ',XL2'002F',CL2'2F' o SUIT0035 DC CL16'RSA_AES256_SHA ',XL2'0035',CL2'35' o SUITENTL EQU 20 Length of a single tab entry o SUITECNT EQU (*-SUITETAB)/SUITENTL Number of entries in table

Nota de uso: lo anterior se puede utilizar para aplicaciones que requieren soporte para los conjuntos de

cifrado más antiguos (SSL 3.0, TLS 1.0 y TLS 1.1).

• TLSVSE GENPROT – generara: o PROTTABL DS 0F o PROT0300 DC XL2'0300',CL5'SSL30',XL1'00' SSL 3.0 created by Netscape o PROT0301 DC XL2'0301',CL5'TLS10',XL1'00' TLS 1.0 defined in RFC2246 o PROT0302 DC XL2'0302',CL5'TLS11',XL1'00' TLS 1.1 defined in RFC4346 o PROT0303 DC XL2'0303',CL5'TLS12',XL1'00' TLS 1.2 defined in RFC5246 o PROTENTL EQU 8 Length of a single tab entry o PROTECNT EQU (*-PROTTABL)/PROTENTL Number of entries in table

Nota de uso: lo anterior se puede utilizar para aplicaciones que requieren soporte para las versiones de

protocolo anteriores (SSL 3.0, TLS 1.0 y TLS 1.1) y TLS 1.2.

• TLSVSE GENCNST –genera la combinación de GENVTLS, GENVCON, GENSUIT, and GENPROT in a single statement.

Nota de uso: Esto se puede usar para aplicaciones que desean admitir todas las posibles versiones de

protocolo y conjuntos de cifrado.

• TLSVSE INLINE – generara las áreas de solicitud del ensamblador en línea. • TLSVSE DSECT – generara las áreas de solicitud del ensamblador en dsects.

212

programmer s guide - csi international, inc

Documents