Initial importv0.1.0

1 files changed, 81 insertions, 0 deletions

diff --git a/copy/cepis.cpy b/copy/cepis.cpy
new file mode 100644
index 0000000..59d643c
--- /dev/null
+++ b/copy/cepis.cpy
@@ -0,0 +1,81 @@
+*> ---------------------------------------------------------------------
+*> cepis 0.1.0 -- public data layouts for the cep.is client.
+*>
+*> Copy this into WORKING-STORAGE (callers) or LINKAGE (subprograms).
+*> It defines, in order:
+*>
+*>   CEPIS-CONFIG      client configuration; fill it with
+*>                     CALL "CEPIS-DEFAULT-CONFIG" before overriding
+*>   CEPIS-STATUS      outcome of the last call, with the six error
+*>                     categories as 88-levels
+*>   CEPIS-CEP-INPUT   a CEP as the user typed it, masked or not
+*>   CEPIS-CEP         the same CEP, 8 digits
+*>   CEPIS-ADDRESS     one address
+*>   CEPIS-HEALTH      the answer of GET /health
+*>   CEPIS-BATCH       the batch table, one slot per requested CEP
+*>
+*> Data field names are the API's own, in Portuguese. Everything else in
+*> this library is English.
+*> ---------------------------------------------------------------------
+
+*> Client configuration. CEPIS-DEFAULT-CONFIG fills every field; change
+*> what you need afterwards. CFG-BASE-URL is the one that usually differs
+*> between environments.
+01  CEPIS-CONFIG.
+    05  CFG-BASE-URL                PIC X(200).
+    05  CFG-TIMEOUT-MS              PIC 9(9).
+    05  CFG-MAX-ATTEMPTS            PIC 9(4).
+    05  CFG-BACKOFF-BASE-MS         PIC 9(9).
+    05  CFG-BACKOFF-MAX-MS          PIC 9(9).
+    05  CFG-TOTAL-TIMEOUT-MS        PIC 9(9).
+    05  CFG-USER-AGENT              PIC X(120).
+
+*> Outcome of the last call. Test CEPIS-OK first; the six failure
+*> categories are split by the decision the caller has to make, not by
+*> the HTTP status that produced them. CEPIS-RETRIABLE covers the three
+*> the client already retried on its own before giving up.
+01  CEPIS-STATUS.
+    COPY "cepis-status.cpy" REPLACING
+        ==:P:== BY ==CEPIS== ==:L1:== BY ==05==.
+
+*> A CEP as the caller has it: "01001-000", "01001000" or "01001.000".
+01  CEPIS-CEP-INPUT                 PIC X(20).
+
+*> The same CEP reduced to its 8 digits by CEPIS-NORMALIZE-CEP.
+01  CEPIS-CEP                       PIC X(8).
+
+*> One address. Fields the database lacks come back as spaces, never as
+*> a marker value. ADDR-GEO-PRESENT says whether the coordinate exists;
+*> ADDR-GEO-LAT and ADDR-GEO-LON are meaningless when it does not.
+01  CEPIS-ADDRESS.
+    COPY "cepis-address.cpy" REPLACING
+        ==:P:== BY ==ADDR== ==:L1:== BY ==05== ==:L2:== BY ==10==.
+
+*> The answer of GET /health. HEALTH-DEGRADED is not an error: the API
+*> reporting itself unwell is the diagnosis you asked for.
+01  CEPIS-HEALTH.
+    05  HEALTH-STATUS               PIC X(20).
+        88  HEALTH-OK               VALUE "ok".
+    05  HEALTH-DNE                  PIC X(20).
+    05  HEALTH-CEPS                 PIC 9(12).
+    05  HEALTH-GEO                  PIC 9(12).
+    05  HEALTH-BASE-GERADA-EM       PIC X(32).
+
+*> The batch table. Fill BATCH-COUNT and BATCH-REQUESTED for each slot,
+*> then CALL "CEPIS-LOOKUP-MANY". Every slot comes back in place: a CEP
+*> that does not exist, or that is not 8 digits, leaves its slot
+*> BATCH-ENTRY-MISSING. Slots are never removed or shifted.
+*>
+*> Batches carry no coordinate: the endpoint behind them is CSV and the
+*> CSV has no geo column, so BAT-GEO-PRESENT is always "N" here even for
+*> CEPs that do have one. Need the coordinate? Use CEPIS-LOOKUP.
+01  CEPIS-BATCH.
+    05  BATCH-COUNT                 PIC 9(4).
+    05  BATCH-ENTRY OCCURS 1000 TIMES.
+        10  BATCH-REQUESTED         PIC X(20).
+        10  BATCH-FOUND             PIC X.
+            88  BATCH-ENTRY-FOUND   VALUE "Y".
+            88  BATCH-ENTRY-MISSING VALUE "N".
+        10  BATCH-ADDRESS.
+            COPY "cepis-address.cpy" REPLACING
+                ==:P:== BY ==BAT== ==:L1:== BY ==15== ==:L2:== BY ==20==.