SWN139 - Importazione documenti da Areagate¶

Nome programma SWN139 Linkage section UTILAGPRG - Linkage comune Id processo: 139 Nome processo: ARPDOCTES Tabelle principali gestite

AREA	AREAGATE	Direzione
COGS26 (documenti magazzino) COGSA0 (buoni prelievo)	ARPDOCTES ARPDOCDET	<------

Logica generale Importazione di documenti di magazzino e buoni prelievo cliente provenienti da Areagate verso il gestionale. Il programma legge le testate e i dettagli dalla tabella Areagate ARPDOCTES/ARPDOCDET e crea i corrispondenti documenti nel gestionale tramite le routine standard COGS26 (documenti magazzino) e COGSA0 (buoni prelievo).

Classi documento gestite

Classe	Descrizione	Routine gestionale
DMG	Documento magazzino generico	COGS26
DMEF	Entrata da fornitore	COGS26
DMUF	Uscita a fornitore	COGS26
BDPC	Buono prelievo cliente	COGSA0

Importazione Il programma legge le testate e i dettagli dei documenti dalla tabella Areagate, li valida e li importa nel gestionale creando i corrispondenti documenti.

Esportazione Non prevista in questo processo.

Programmi chiamati

Programma	Scopo
COGS26	Creazione documenti magazzino (operazione "Inserimento")
COGSA0	Creazione buoni prelievo (operazioni CREA-BDP-SINGOLO / AGGIUNGI-A-BDP)
RNEWCONF	Lettura configurazioni
SWGETS	Connessione database PostgreSQL
GESSTR	Conversione testi importati (CONV-TESTO-IMPORTATO)
COGS62	Calcolo durata processo

Configurazioni possibili

Gruppo	Parametro	Note
abilita	attiva-areaapp	Deve valere "S"
areaapp	cod-azienda
areaapp	db-conn-string
areaapp	agg-postgres-online
areaapp	AGLANCIO-ATTIVO	Deve valere "S" per abilitare il processo
doc-mag	causale-dmg	Causale per documenti magazzino generici (obbligatoria)
doc-mag	causale-dmef	Causale per entrata da fornitore (obbligatoria)
doc-mag	causale-dmuf	Causale per uscita a fornitore (obbligatoria)
db	db-log-level	Livello di log database
assist	gestione-gruppo-aziende	Gestione gruppi aziende

Elaborazione Tipi di segnalazione: Vedi Tipi di segnalazione A - Controllo di esecuzione Vedi Controllo di esecuzione A.2 - Apertura A.2.1 Apertura tabelle Tentare l'apertura della tabella da sincronizzare: ARPDOCTES Se fallita inviare una Segnalazione critica e chiudere.

C - Importazione documenti Effettuare una query per estrarre tutti i documenti da importare: SELECT * FROM ARPDOCTES WHERE a_dotes_azi = azienda AND a_dotes_agg_app <> ' '

Per ciascun documento:

Validazione classe documento: verificare che la classe (DMG, DMEF, DMUF, BDPC) sia gestita
Ricerca anagrafica: trovare il codice anagrafica gestionale corrispondente al cliente/fornitore Areagate
Ricerca merci: per ogni riga di dettaglio, trovare il codice merce gestionale corrispondente

C.1 - Importazione documenti magazzino (DMG, DMEF, DMUF) Per le classi DMG, DMEF, DMUF:

Creare il file di transito TRAN-S26 con nome univoco (swn139_cogs26_YYYYMMDD_HHMMSS)
Leggere tutte le righe da ARPDOCDET per il documento
Per ogni riga (c1-dm-prepara-riga):
Ricerca merce su COGMERCI (obbligatoria)
Determinazione segno: E=entrata, U=uscita (dal tipo documento se non specificato)
Valorizzazione prezzi se presenti
Righe con val = 'C' (cancellate) vengono saltate
Richiamare COGS26 con operazione "Inserimento":
Causale: da documento, oppure da configurazione (dmg/dmef/dmuf)
Tipo documento: "C" per DMEF (carico), "I" per DMUF (scarico)
Note: 50+50 caratteri dalle note documento
Se successo (s26-o-esito="S"):
Comporre la chiave documento (mag/anno/tipo/numero)
Aggiornare a_dotes_key_area con la chiave creata
Per DMEF: aggiornare COGTESBO con numero/data documento fornitore
Se errore: segnalare e non aggiornare ARPDOCTES

C.2 - Importazione buoni prelievo (BDPC) Per la classe BDPC:

Cercare il raccordo con l'ordine padre tramite ARPDOCRAC (figlio_id_pub = documento corrente, figlio_riga = 0)
Trovare la testata ordine su ARPORTES per ottenere tor_chia
Leggere tutte le righe da ARPDOCDET
Per ogni riga valida (c1-bdpc-riga):
Ricerca merce su COGMERCI (obbligatoria)
Se ordine trovato: cercare la consegna corrispondente su COGCONOR:
- Match per ordine + merce
- Solo consegne aperte (fl-close <> 'C')
- Verificare quantita' residua (qta - qtacons - somma BDP aperti) >= quantita' riga
Prima riga: richiamare COGSA0 con operazione CREA-BDP-SINGOLO
Righe successive: richiamare COGSA0 con operazione AGGIUNGI-A-BDP usando la chiave BDP memorizzata
Se almeno una riga valida creata: aggiornare a_dotes_key_area con chiave BDP (mag/anno/numero)

Gestione semaforo Il programma usa il campo A-SYN-SEMAFORO su APSTATOSYN per evitare collisioni: - Se vale "A": Areagate in uso, skip completo dell'elaborazione - All'inizio: imposta a "G" (Gestionale in elaborazione) - Al termine: rilascia (reset a spazi)

Sync ID Incremento atomico su APSTATOSYN.a_syn_id_sincro tramite UPDATE...RETURNING. Memorizzato su a-dotes-id-sincro per ogni documento importato con successo.

B.9 - Aggiornamento stato Al termine dell'elaborazione, aggiornare il record APSTATOSYN:

Dato	Contenuto
A-SYN-AZIENDA	Codice azienda
A-SYN-TABELLA	"ARPDOCTES"
A-SYN-DA-ID-SINCRO	Ultimo id sincro + 1
A-SYN-VERSIONE	1

Contatori

Contatore	Descrizione
tm-r-let	Record letti
tm-r-imp	Record importati
tm-r-gia	Record gia' presenti (warning)
tm-r-err	Record con errore

Documentazione tecnica generata automaticamente — 2026-03-20 (aggiornamenti incrementali fino al 2026-05-21)

Storico modifiche¶

Correzione campo documento interlocutore (aprile 2026)¶

Nella sezione di aggiornamento COGTESBO dopo la creazione del documento, i campi di riferimento per numero e data bolla fornitore sono stati corretti: - a-dotes-key-host → a-dotes-doc-interlocutore (per tes-nbolfor) - a-dotes-data → a-dotes-data-doc-interlocutore (per tes-dabolfor)

Questo allineamento riflette la rinomina dei campi nella copybook arpdoctes.cpy per distinguere chiaramente il documento dell'interlocutore dalla chiave host Areagate.

Pre-validazione del dettaglio BDPC (2026-05-14)¶

Introdotta la pre-validazione del dettaglio prima di iniziare la creazione del BDP. La modifica risponde alla necessita' di evitare BDP parziali (alcune righe create, altre saltate) quando il dettaglio contiene errori bloccanti.

Flusso aggiornato:

Subito dopo c1-bdpc-cerca-raccordo, il programma invoca il nuovo paragrafo c1-bdpc-prevalida che scorre tutte le righe ARPDOCDET (escluse quelle con a-dodet-val = "C") tramite la SQL gia' esistente, e per ogni riga chiama c1-bdpc-prevalida-riga:
Lookup merce su COGMERCI tramite c1-lookup-merce: se w-fl-merce-trovata = "N" viene loggato un errore critico-cliente e impostato w-bdp-errore = "S".
Se c'e' un raccordo con un ordine (w-rac-trovato = "S"), chiamata a c1-bdpc-cerca-consegna: se la consegna non e' trovata su COGCONOR, l'errore e' gia' loggato all'interno del paragrafo e viene solo impostato w-bdp-errore = "S".
Il loop non si interrompe al primo errore: scorre tutto il dettaglio per loggare ogni problema.
Se al termine w-bdp-errore = "S":
Viene loggato il messaggio "Documento {id_pub}: import annullato per errori sul dettaglio" come critico-cliente.
Il documento viene comunque marcato come elaborato in ARPDOCTES (perform c1-aggiorna-arpdoctes) per evitare di riproporlo alle prossime esecuzioni.
exit paragraph interrompe il flusso prima di entrare nel loop di creazione BDP.
Se la pre-validazione passa (w-bdp-errore = "N"), il flusso prosegue inalterato sul loop di creazione delle righe BDP.

Cambiamento di semantica errori consegna: in precedenza, la mancata consegna trovata su COGCONOR generava un warning e il BDP veniva creato comunque "senza collegamento". Ora la condizione e' bloccante per l'intero documento (nessun BDP creato) e il messaggio non riporta piu' la frase "BDP creato senza collegamento".

Safety net difensiva: in c1-bdpc-riga, il controllo di esistenza merce e' mantenuto come safety net: in caso di skew tra pre-validazione e creazione (es. cancellazione concorrente della merce) il sistema continua a non scrivere righe BDP con merce mancante, ma in pratica la pre-validazione previene la condizione.

Nuova variabile: w-bdp-errore PIC X(01) — flag locale.

Effetti collaterali: nessuno su altri programmi. La modifica e' isolata al flusso di import documenti Areagate per classe BDPC.

Note aggiuntive di riga BDP via TRAN-S26D (2026-05-15)¶

Estensione del flusso di scrittura BDP per propagare le note di riga presenti in a-dodet-note di ARPDOCDET verso COGS26.

Per ogni documento BDPC, prima del loop di scrittura dettaglio, viene creato un nuovo file di transito TRAN-S26D (line-sequential) con nome dinamico swn139_cogs26d_{datasis}_{orasis} sotto ext-tmp-dir. Il nome viene anche memorizzato in s26-nome-tran-s26d. Il file TRAN-S26D viene aperto in I/O subito dopo il TRAN-S26 esistente, con gestione errore (segnalazione + chiusura testata e uscita dal paragrafo).

Sul dettaglio, per ciascuna riga ARPDOCDET con a-dodet-note non vuoto viene scritto un record trs-s26d-rec con:

trs-s26d-classe = " "
trs-s26d-riga = w-trs-rig (progressivo riga corrente del TRAN-S26)
trs-s26d-riga-pro = 1
trs-s26d-des = a-dodet-note
trs-s26d-fl-sost = " " (no sostituzione)

Prima della chiamata a COGS26, il record di testata TRAN-S26 viene arricchito con s26-fl-desc-agg = "S" e il nome file viene esposto in s26-nome-tran-s26d. Dopo il ritorno da COGS26, sia TRAN-S26 sia TRAN-S26D vengono chiusi e cancellati (anche in caso di esito negativo nel ramo di gestione errore).

Nuove variabili working storage: w-nome-tran-s26d PIC X(200), s26d-nome-file PIC X(80).

Dipendenza: la copybook tran-s26d e la SELECT/FD del file di transito devono essere disponibili nel programma (gestite tramite il generatore Screens).

Import Serial Number su BDPC (2026-05-21)¶

Esteso il flusso BDPC con l'importazione dei serial number trasmessi nel campo a_dodet_note dell'API documenti (vedi sezione "Serial number" in API Documenti). Per ciascuna riga BDPC il programma:

Verifica se la merce gestionale ha il flag mer-fl-sn = "T" (matricolata, valorizzato dalla nuova assegnazione in c1-lookup-merce). Se la merce non e' matricolata oppure a_dodet_note e' vuoto, l'elaborazione S/N viene saltata.
Esegue lo splitting del buffer note tramite il paragrafo splitta-sn-list (separatore "; ", massimo 100 token in w-sn-array, buffer 2000 byte gia' validato dall'API).
Verifica che il numero di S/N estratti corrisponda alla quantita' di riga (a-dodet-qta); in caso contrario emette un warning gesdebug-write-warning ma prosegue.
Compone la chiave testata BDP appena creato leggendo cogsa0-o-bdp-mag/ann/num (restituiti da COGSA0).
Per ogni token (w-sn-curr):
Normalizza il case secondo ext-case-sn (I=invariato, U=upper-case, default lower-case), pattern allineato a SWN140/COGZS27.
Salta i token vuoti dopo trim (w-sn-len = 0).
Risolve la matricola via COGU07 (operazione cerca-sn-link, u07-i-fl-clock = "N", u07-fl-figlia-comunque = "N").
Se la matricola non esiste, scrive comunque un legame COGGENER tipo CS (serial in chiaro) con gnr-parte-2 = w-sn-norm; log critico-cliente "S/N non trovato in anagrafica matricole".
Se la matricola esiste ma appartiene a una merce diversa (u07-merce <> w-merce-gest), il S/N viene scartato (log critico-cliente, decremento w-prog-sn).
Se la matricola e' gia' allocata su un altro BDP (lookup COGGENER chiave 2 con gnr-tip = "CM" e gnr-parte-2 = u07-mat-figlia, escludendo gnr-parte-1 = tbp-chia1), il S/N viene scartato (log critico-cliente "gia' allocato su BdP ...", decremento w-prog-sn).
Altrimenti scrive un legame COGGENER tipo CM (matricola) con gnr-parte-1 = tbp-chia1, gnr-parte-2 = u07-mat-figlia, gnr-prog = w-prog-sn, gnr-merce = u07-merce.
Log informativo per ogni legame inserito ("Inserito legame S/N {sn} (tip CM|CS) su BdP {mag}/{ann}/{num}").

Nuove copybook: utilu07.cpy (linkage subroutine matricole), coggener.k02 (chiave secondaria matricola per il controllo di allocazione).

Nuove variabili working storage (gruppo w-sn-import):

w-mer-fl-sn PIC X(01) — flag merce matricolata, valorizzato in c1-lookup-merce da mer-fl-sn.
w-sn-list-buffer PIC X(2000) — buffer di splitting.
w-sn-array OCCURS 100 — array dei token.
w-sn-count, w-sn-idx, w-pos-ptr, w-prog-sn, w-sn-len — contatori e progressivi.
w-sn-curr, w-sn-norm PIC X(30) — token corrente e normalizzato.
w-fine-parsing PIC X(01) — controllo loop UNSTRING.

Nuovi paragrafi:

splitta-sn-list — UNSTRING in loop su "; " con guardrail su w-pos-ptr > 2000.
c1-bdpc-elabora-sn — orchestrazione completa import S/N.

Dipendenze: configurazione ext-case-sn (da SETENV), sottoprogramma COGU07 (servizio matricole padre-figlio).

Errori bloccanti: solo wr-coggener con verbo invalido (log critico-es2000 + uscita paragrafo). Gli errori sui singoli S/N (non trovato, merce diversa, gia' allocato) sono "soft": il BDP resta valido e gli altri S/N coerenti vengono comunque collegati.

Data documento da interlocutore (2026-05-21)¶

Il campo s26-data ora viene popolato con a-dotes-data-doc (data documento) anziche' con datasis (data di sistema). Questo allinea la data registrata sul documento gestionale alla data effettiva del documento originale Areagate, evitando lo shift quando l'import avviene in differita.

Import Serial Number su DMEF (2026-05-22)¶

Esteso il flusso documenti magazzino con l'importazione dei serial number trasmessi nel campo a_dodet_note dei documenti di entrata da fornitore (classe = DMEF). A differenza dell'import BDPC (che produce legami COGGENER su un BdP esistente), su DMEF i serial number creano nuove matricole in COGMATRI tramite il flusso standard di COGS26 con s26-fl-matricole = "C" (vedi tracciato COGS26).

Apertura file di transito

In c1-importa-doc-mag, oltre a TRAN-S26 e TRAN-S26D viene aperto un terzo file di transito TRAN-S26B (nome dinamico #tr-s26b.{oper} sotto ext-tmp-dir) solo se la classe del documento e' k-doc-tip-doc-entrata-forn (DMEF). Il flag w-fl-s26b-aperto = "S" traccia l'apertura. In caso di errore di apertura il documento viene saltato e tutti i file di transito vengono cancellati.

Parsing note di riga

Per ciascuna riga DMEF con a_dodet_note <> spaces e merce a S/N (mer-fl-sn = "T"), viene invocato il nuovo paragrafo parse-note-dmef che:

Copia le note in upper-case su w-note-buffer-up e ricerca manualmente la sottostringa "S/N: " (case-insensitive).
Se il marker non e' presente, w-fl-sn-presenti = "N" e l'intera nota va in TRAN-S26D come gia' previsto.
Se il marker e' presente:
w-note-pulita riceve la parte di nota pre-marker, con trim del separatore "; " finale.
w-sn-section riceve la parte post-marker (lista S/N separati da "; ").
Solo w-note-pulita viene scritta su TRAN-S26D (la lista S/N non finisce nelle note descrittive del documento).

Scrittura S/N su TRAN-S26B

Il paragrafo scrivi-sn-section-tran-s26b esegue lo splitting di w-sn-section tramite splitta-sn-list (separatore "; ", max 100 token, vedi documentazione sezione BDPC). Per ciascun S/N estratto chiama scrivi-sn-tran-s26b che:

Verifica la lunghezza (> 30 => scarta con warning).
Inizializza trs-s26b-rec con: trs-s26b-rig = w-trs-rig (riga corrente TRAN-S26), trs-s26b-merce = w-merce-gest, trs-s26b-segno = "E" (sempre entrata per DMEF), trs-s26b-sn = w-sn-curr (S/N estratto).
trs-s26b-mat-ann = 0 e trs-s26b-mat-num = w-sn-mat-counter (contatore globale w-sn-mat-counter incrementato): la matricola e' un placeholder che serve solo a garantire l'uniqueness della chiave chia1 = rig + merce + mat su TRAN-S26B. Il vero serial number e' in trs-s26b-sn.
Setta w-fl-s26b-scritta = "S" al primo write riuscito.

Conteggio S/N vs quantita' riga

Se il numero di S/N estratti non coincide con a-dodet-qta, viene emesso un warning ma il flusso prosegue (l'operatore puo' completare manualmente o correggere la nota).

Attivazione import matricole su COGS26

Subito prima della call a COGS26 per la testata, se w-fl-s26b-scritta = "S" viene impostato s26-fl-matricole = "C" (k-s26-ges-matricole-arrivo, valore nuovo). COGS26 in questa modalita' legge il TRAN-S26B con le S/N nuove e crea le matricole via COGU07 (operazione crea-matricola) usando trs-s26b-sn come sn-padre e ignorando trs-s26b-mat (vedi storico modifiche di COGS26).

Nuove variabili working storage

w-fl-s26b-aperto PIC X(01) — flag apertura TRAN-S26B per il documento corrente.
w-fl-s26b-scritta PIC X(01) — flag scrittura di almeno una riga S/N.
w-sn-mat-counter PIC 9(08) — contatore globale matricole-placeholder.
Gruppo parsing note: w-note-buffer-up, w-pos-marker, w-pos-sn, w-note-len, w-fl-sn-presenti, w-note-pulita, w-note-eff, w-sn-section, w-sn-len.

Nuovi paragrafi

parse-note-dmef — estrazione marker S/N dalle note (upper-case search, trim).
scrivi-sn-section-tran-s26b — splitting e validazione conteggio.
scrivi-sn-tran-s26b — write singolo S/N su TRAN-S26B.

Limiti

Solo DMEF: per DMG e DMUF il marker "S/N: " viene ignorato (sezione note ritorna integralmente in TRAN-S26D).
Solo merci con mer-fl-sn = "T": l'estrazione e' saltata per merci non matricolate (la nota integrale finisce in TRAN-S26D).
Massimo 100 S/N per riga (buffer w-sn-array OCCURS 100).