DEALLOCATE

  • Artículo

El verbo DEALLOCATE desasigna una conversación entre dos programas de transacción (CSP).

En la estructura siguiente se describe el bloque de control de verbos (VCB) usado por el verbo DEALLOCATE .

Sintaxis

  
struct deallocate {  
    unsigned short       opcode;  
    unsigned char        opext;  
    unsigned char        reserv2;  
    unsigned short       primary_rc;  
    unsigned long        secondary_rc;  
    unsigned char        tp_id[8];  
    unsigned long        conv_id;  
    unsigned char        reserv3;  
    unsigned char        dealloc_type;  
    unsigned short       log_dlen;  
    unsigned char FAR *  log_dptr;  
    void                 (WINAPI *callback)();  
    void                 *correlator;  
    unsigned char        reserv6[4];  
};

Miembros

opcode
Parámetro proporcionado. Especifica el código de operación de verbo, AP_B_DEALLOCATE.

opext
Parámetro proporcionado. Especifica la extensión de operación de verbo, AP_BASIC_CONVERSATION.

reserv2
Campo reservado.

primary_rc
Parámetro devuelto. Especifica el código de retorno principal que establece APPC al finalizar el verbo. Los códigos de retorno válidos varían en función del verbo APPC que se emita. Consulte la sección de códigos de retorno para obtener los códigos de error válidos para este verbo.

secondary_rc
Parámetro devuelto. Especifica el código de retorno secundario que establece APPC al finalizar el verbo. Los códigos de retorno válidos varían en función del verbo APPC que se emita. Consulte la sección de códigos de retorno para obtener los códigos de error válidos para este verbo.

tp_id
Parámetro proporcionado. Identifica el TP local. El valor de este parámetro lo devolvió TP_STARTED en el TP invocado o por RECEIVE_ALLOCATE en el TP invocado.

conv_id
Parámetro proporcionado. Identifica la conversación establecida entre los dos CSP. El valor de este parámetro lo devuelve ALLOCATE en el TP invocado o por RECEIVE_ALLOCATE en el TP invocado.

reserv3
Campo reservado.

dealloc_type
Parámetro proporcionado. Especifica cómo realizar la desasignación.

El uso de uno de los siguientes valores desasigna la conversación de forma anómala:

  • AP_ABEND_PROG

  • AP_ABEND_SVC

  • AP_ABEND_TIMER

    Si la conversación está en estado SEND cuando el TP local emite DEALLOCATE, APPC envía el contenido del búfer de envío de la unidad lógica local (LU) al TP del asociado antes de desasignar la conversación. Si la conversación está en estado RECEIVE o PENDING_POST, APPC purga los datos entrantes antes de desasignar la conversación.

    Un TP de aplicación o servicio debe especificar AP_ABEND_PROG cuando encuentre un error que impida la finalización correcta de una transacción.

    Un TP de servicio debe especificar AP_ABEND_SVC cuando encuentre un error causado por su TP del servicio asociado (por ejemplo, un error de formato en la información de control enviada por el TP del servicio de asociado). Un TP de servicio debe especificar AP_ABEND_TIMER cuando encuentra un error que requiere desasignación inmediata (por ejemplo, un operador que termina el programa prematuramente).

    AP_FLUSH envía el contenido del búfer de envío de lu local al TP del asociado antes de desasignar la conversación. Este valor solo se permite si la conversación está en estado SEND.

    AP_SYNC_LEVEL usa el nivel de sincronización de la conversación (establecido por ALLOCATE) para determinar cómo desasignar la conversación. Este valor solo se permite si la conversación está en estado SEND.

    Si el nivel de sincronización de la conversación es AP_NONE, APPC envía el contenido del búfer de envío de la LU local al TP del asociado antes de desasignar la conversación.

    Si el nivel de sincronización es AP_CONFIRM_SYNC_LEVEL, APPC envía el contenido del búfer de envío de la LU local y una solicitud de confirmación al TP del asociado. Tras recibir la confirmación del TP del asociado, APPC desasigna la conversación. Sin embargo, si el TP del asociado notifica un error, la conversación permanece asignada.

    log_dlen
    Parámetro proporcionado. Especifica el número de bytes de datos que se van a enviar al archivo de registro de errores. El intervalo es de 0 a 32767.

    Puede establecer este parámetro en un número mayor que cero si dealloc_type está establecido en AP_ABEND_PGM, AP_ABEND_SVC o AP_ABEND_TIMER. De lo contrario, este parámetro debe ser cero.

    log_dptr
    Parámetro proporcionado. Proporciona la dirección del búfer de datos que contiene información de error. Los datos se envían al registro de errores local y a la LU del asociado.

    DealLOCATE usa este parámetro si log_dlen es mayor que cero.

    Para Microsoft Windows, el búfer de datos puede residir en un área de datos estática o en un área asignada globalmente. El búfer de datos debe ajustarse completamente dentro de esta área.

    En el caso del sistema operativo/2, el búfer de datos de registro debe residir en un segmento compartido sin nombre, asignado por la función DosAllocSeg con marcas iguales a 1. El búfer de datos de registro debe caber completamente en el segmento.

    El TP debe dar formato a los datos de error como una variable de registro de errores de GDS. Para obtener más información, consulte los manuales de IBM SNA.

    callback
    Parámetro proporcionado. Solo está presente si el bit de AP_EXTD_VCB está establecido en el miembro opext , lo que indica la compatibilidad con el punto de sincronización. Este parámetro es la dirección de una función de devolución de llamada proporcionada por el usuario. Si este campo es NULL, no se proporcionará ninguna notificación.

    El prototipo de la rutina de devolución de llamada es el siguiente:

void WINAPI callback_proc(  
    struct appc_hdr *vcb,  
    unsigned char tp_id[8],  
    unsigned long conv_id,  
    unsigned short type,  
    void *correlator  
   );

El procedimiento de devolución de llamada puede tomar cualquier nombre, ya que la dirección del procedimiento se pasa al archivo DLL de APPC. Los parámetros pasados a la función son los siguientes:

Vcb

Puntero al bloque de control de verbo DEALLOCATE que provocó que la conversación se desasigne.

tp_id

Identificador tp del TP que pertenece a la conversación desasignada.

conv_id

Identificador de conversación de la conversación desasignada.

tipo

Tipo del flujo de mensajes que provocó que se invoque la devolución de llamada. Los valores posibles son:

AP_DATA_FLOW

Flujo de datos normal en la sesión.

AP_UNBIND

La sesión se desenlazó normalmente.

AP_FAILURE

La sesión finalizó debido a una interrupción.

Correlacionador

Este valor es el correlator especificado en el verbo DEALLOCATE .

Correlacionador
Parámetro proporcionado. Solo está presente si el bit de AP_EXTD_VCB está establecido en el miembro opext , lo que indica la compatibilidad con la API de punto de sincronización. Este campo de correlador permite al TP especificar un valor que puede usar para correlacionar una llamada a la función de devolución de llamada con, por ejemplo, sus propias estructuras de datos internas. Este valor se devuelve al TP como uno de los parámetros de la rutina de devolución de llamada cuando se invoca.

reserv4
Campo reservado.

Códigos de retorno

AP_OK
Código de retorno principal; el verbo se ha ejecutado correctamente.

AP_PARAMETER_CHECK
Código de retorno principal; el verbo no se ha ejecutado debido a un error en un parámetro.

AP_BAD_CONV_ID

Código de retorno secundario; el valor de conv_id no coincide con un identificador de conversación asignado por APPC.

AP_BAD_TP_ID

Código de retorno secundario; el valor de tp_id no coincide con un identificador de TP asignado por APPC.

AP_DEALLOC_BAD_TYPE

Código de retorno secundario; el parámetro dealloc_type no se estableció en un valor válido.

AP_DEALLOC_LOG_LL_WRONG

Código de retorno secundario; El campo LL de la variable de registro de errores de GDS no coincidía con la longitud real de los datos de registro.

AP_INVALID_DATA_SEGMENT

Código de retorno secundario; los datos de error del archivo de registro eran más largos que el segmento asignado para contener los datos de error o la dirección del búfer de datos de error era incorrecta.

AP_STATE_CHECK
Código de retorno principal; el verbo no se ejecutó porque se emitió en un estado no válido.

AP_DEALLOC_CONFIRM_BAD_STATE

Código de retorno secundario; la conversación no estaba en estado SEND y el TP intentó vaciar el búfer de envío y enviar una solicitud de confirmación. Este intento se produjo porque el valor de dealloc_type se AP_SYNC_LEVEL y el nivel de sincronización de la conversación se AP_CONFIRM_SYNC_LEVEL.

AP_DEALLOC_FLUSH_BAD_STATE

Código de retorno secundario; la conversación no estaba en estado SEND y el TP intentó vaciar el búfer de envío. Este intento se produjo porque el valor de dealloc_type era AP_FLUSH o porque el valor de dealloc_type era AP_SYNC_LEVEL y el nivel de sincronización de la conversación era AP_NONE. En cualquier caso, la conversación debe estar en el estado SEND.

AP_DEALLOC_NOT_LL_BDY

Código de retorno secundario; la conversación estaba en estado SEND y el TP no terminó de enviar un registro lógico. El parámetro dealloc_type se estableció en AP_SYNC_LEVEL o AP_FLUSH.

AP_ALLOCATION_ERROR
Código de retorno principal; APPC no ha podido asignar una conversación. El estado de la conversación se establece en RESET.

Este código se puede devolver a través de un verbo emitido después de ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Código de retorno secundario; la conversación no se puede asignar debido a una condición permanente, como un error de configuración o un error de protocolo de sesión. Para determinar el error, el administrador del sistema debe examinar el archivo de registro de errores. No vuelva a intentar la asignación hasta que se haya corregido el error.

AP_ALLOCATION_FAILURE_RETRY

Código de retorno secundario; No se pudo asignar la conversación debido a una condición temporal, como un error de vínculo. El motivo del error se registra en el registro de errores del sistema. Vuelva a intentar la asignación.

AP_CONVERSATION_TYPE_MISMATCH

Código de retorno secundario; El LU del asociado o TP no admite el tipo de conversación (básico o asignado) especificado en la solicitud de asignación.

AP_PIP_NOT_ALLOWED

Código de retorno secundario; la solicitud de asignación especificó datos pip, pero el TP del asociado no requiere estos datos o la LU del asociado no la admite.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Código de retorno secundario; el TP del asociado requiere datos pip, pero la solicitud de asignación no especificó datos pip ni un número incorrecto de parámetros.

AP_SECURITY_NOT_VALID

Código de retorno secundario; el identificador de usuario o la contraseña especificados en la solicitud de asignación no fue aceptado por la LU del asociado.

AP_SYNC_LEVEL_NOT_SUPPORTED

Código de retorno secundario; el TP del asociado no admite el sync_level (AP_NONE o AP_CONFIRM_SYNC_LEVEL) especificado en la solicitud de asignación o no se reconoció el sync_level .

AP_TP_NAME_NOT_RECOGNIZED

Código de retorno secundario; la LU del asociado no reconoce el nombre de TP especificado en la solicitud de asignación.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Código de retorno secundario; la LU remota rechazó la solicitud de asignación porque no pudo iniciar el TP del asociado solicitado. La condición es permanente. El motivo del error se puede registrar en el nodo remoto. No vuelva a intentar la asignación hasta que se haya corregido el error.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Código de retorno secundario; la LU remota rechazó la solicitud de asignación porque no pudo iniciar el TP del asociado solicitado. La condición puede ser temporal, como un tiempo de espera. El motivo del error se puede registrar en el nodo remoto. Vuelva a intentar la asignación.

AP_COMM_SUBSYSTEM_ABENDED
Código de retorno principal; indica una de las condiciones siguientes:

  • El nodo utilizado por esta conversación encontró una anulación.

  • La conexión entre el TP y el nodo PU 2.1 se interrumpió (un error de LAN).

  • El proceso SnaBase que se ejecuta en el equipo del TP encontró una anulación.

    El administrador del sistema debe examinar el registro de errores a fin de determinar el motivo de la anulación.

    AP_COMM_SUBSYSTEM_NOT_LOADED
    Código de retorno principal; no se pudo cargar o finalizar un componente necesario durante el procesamiento del verbo. Por tanto, no se pudo establecer la comunicación. Consulte al administrador del sistema para aplicar una acción correctiva.

    AP_CONV_FAILURE_NO_RETRY
    Código de retorno principal; la conversación se finalizó debido a una condición permanente, como un error de protocolo de sesión. El administrador del sistema debe examinar el registro de errores del sistema para determinar la causa del error. No vuelva a intentar la conversación hasta que se corrija el error.

    AP_CONV_FAILURE_RETRY
    Código de retorno principal; la conversación se finalizó debido a un error temporal. Reinicie el TP para ver si el problema se produce de nuevo. Si es así, el administrador del sistema debe examinar el registro de errores para determinar la causa del error.

    AP_CONVERSATION_TYPE_MIXED
    Código de retorno principal; el TP ha emitido verbos de conversación básicos y asignados. Solo se puede emitir un tipo en una sola conversación.

    AP_INVALID_VERB_SEGMENT
    Código de retorno principal; el bloque de control de verbo (VCB) se ha extendido más allá del final del segmento de datos.

    AP_PROG_ERROR_PURGING
    Código de retorno principal; mientras que en ESTADO RECEIVE, PENDING, PENDING_POST, CONFIRM, CONFIRM_SEND o CONFIRM_DEALLOCATE, el TP de asociado emitido SEND_ERROR con err_type establecido en AP_PROG. Los datos enviados pero aún no recibidos se purgan.

    AP_STACK_TOO_SMALL
    Código de retorno principal; el tamaño de la pila de la aplicación es demasiado pequeño para ejecutar el verbo. Aumente el tamaño de pila de la aplicación.

    AP_CONV_BUSY
    Código de retorno principal; solo puede haber un verbo de conversación pendiente a la vez en cualquier conversación. Esto puede ocurrir si el TP local tiene varios subprocesos y más de un subproceso emite llamadas APPC con la misma conv_id.

    AP_THREAD_BLOCKING
    Código de retorno principal; el subproceso que llama ya está en una llamada de bloqueo.

    AP_UNEXPECTED_DOS_ERROR
    Código de retorno principal; el sistema operativo devolvió un error a APPC al procesar una llamada de APPC desde el TP local. El código de retorno del sistema operativo se devuelve a través de secondary_rc. Aparece en el orden de intercambio de bytes de Intel. Si el problema persiste, consulte con el administrador del sistema.

    AP_DEALLOC_ABEND_PROG
    Código de retorno principal; la conversación se ha desasignado por uno de los siguientes motivos:

  • El TP de asociado emitió DEALLOCATE con dealloc_type establecido en AP_ABEND_PROG.

  • El TP de asociado ha encontrado un ABEND, lo que hace que la LU del asociado envíe una solicitud DEALLOCATE .

    AP_DEALLOC_ABEND_SVC
    Código de retorno principal; la conversación se ha desasignado porque el TP del asociado emitió DEALLOCATE con dealloc_type establecido en AP_ABEND_SVC.

    AP_DEALLOC_ABEND_TIMER
    Código de retorno principal; la conversación se ha desasignado porque el TP de asociado emitió DEALLOCATE con dealloc_type establecido en AP_ABEND_TIMER.

    AP_SVC_ERROR_PURGING
    Código de retorno principal; el TP de asociado (o LU de asociado) emitido SEND_ERROR con err_type establecido en AP_SVC mientras se encuentra en ESTADO RECEIVE, PENDING_POST, CONFIRM, CONFIRM_SEND o CONFIRM_DEALLOCATE. Es posible que se hayan purgado los datos enviados al TP del asociado.

Comentarios

Según el valor del parámetro dealloc_type , la conversación puede estar en uno de los estados indicados en la tabla siguiente cuando el TP emite DEALLOCATE.

dealloc_type Estado permitido
AP_FLUSH ENVIAR
AP_SYNC_LEVEL ENVIAR
AP_ABEND Cualquiera excepto RESET
AP_ABEND_PROG Cualquiera excepto RESET
AP_ABEND_SVC Cualquiera excepto RESET
AP_ABEND_TIMER Cualquiera excepto RESET

Los cambios de estado, resumidos en la tabla siguiente, se basan en el valor del primary_rc.

primary_rc Nuevo estado
AP_OK RESET
AP_ALLOCATION_ERROR RESET
AP_CONV_FAILURE_RETRY RESET
AP_CONV_FAILURE_NO_RETRY RESET
AP_DEALLOC_ABEND RESET
AP_DEALLOC_ABEND_PROG RESET
AP_DEALLOC_ABEND_SVC RESET
AP_DEALLOC_ABEND_TIMER RESET
AP_PROG_ERROR_PURGING RECEIVE
AP_SVC_ERROR_PURGING RECEIVE

Antes de desasignar la conversación, este verbo realiza el equivalente de uno de los siguientes:

  • FLUSH, enviando el contenido del búfer de envío de lu local al LU asociado (y TP).

  • CONFIRME, enviando el contenido del búfer de envío de la LU local y una solicitud de confirmación al TP del asociado.

    Una vez que este verbo se ha ejecutado correctamente, el identificador de conversación ya no es válido.

    El punto de sincronización de LU 6.2 puede usar una optimización de los flujos de mensajes conocidos como olvidados implícitos. Cuando el protocolo especifica que se requiere un encabezado FORGET PS, el siguiente flujo de datos de la sesión implica que se ha recibido forget. En la situación normal, el TP es consciente del siguiente flujo de datos cuando se reciben o envían datos en una de sus conversaciones de punto de sincronización.

    Sin embargo, es posible que el último mensaje que fluya se debe a que la conversación se desasigna. En este caso, el TP no es consciente cuando se produce el siguiente flujo de datos en la sesión. Para proporcionar el TP con esta notificación, el verbo DEALLOCATE se modifica para permitir que el TP registre una función de devolución de llamada a la que se llamará:

  • En la primera transmisión de flujo normal (solicitud o respuesta) sobre la sesión utilizada por la conversación.

  • Si la sesión está desenlazada antes de cualquier otro flujo de datos.

  • Si la sesión finaliza anómalamente debido a una interrupción del DLC.

    El verbo DEALLOCATE también contiene un miembro de campo de correlación que se devuelve como uno de los parámetros cuando se invoca la función de devolución de llamada. La aplicación puede usar este parámetro de cualquier manera (por ejemplo, como puntero a un bloque de control dentro de la aplicación).

    El TP puede usar el parámetro de tipo pasado a la función de devolución de llamada para determinar si el flujo de mensajes indica que se ha recibido un olvido implícito.

    Tenga en cuenta que el verbo DEALLOCATE probablemente se completará antes de llamar a la rutina de devolución de llamada. La conversación se considera que está en estado RESET y no se puede emitir ningún verbo adicional mediante el identificador de conversación. Si la aplicación emite un verbo TP_ENDED antes del siguiente flujo de datos de la sesión, no se invocará la rutina de devolución de llamada.

    Host Integration Server permite a los CSP desasignar conversaciones inmediatamente después de enviar datos especificando el parámetro de tipo en SEND_DATA como AP_SEND_DATA_DEALLOC_*. Sin embargo, los verbos SEND_DATA no contienen la función de devolución de llamada olvidada implícita. Los CSP que quieran recibir notificaciones de olvido implícitas deben emitir DEALLOCATE explícitamente.