Download as
Browse Code »

Commit 1fcc324ed719e87d5e8f23927ff2549e7a8cbfe6

Authored by Perry Werneck
1 parent d021aee6
Exists in master and in 3 other branches develop, macos, network_module

Updating docs

Showing 4 changed files with 75 additions and 38 deletions   Show diff stats
src/include/lib3270.h
  Diff comments   View file @1fcc324
... ... @@ -1052,23 +1052,23 @@
1052 1052 /**
1053 1053 * @brief Find the buffer address of the field attribute for a given buffer address.
1054 1054 *
1055   - * @param h Session handle.
1056   - * @param addr Buffer address of the field.
  1055 + * @param hSession Session handle.
  1056 + * @param addr Buffer address of the field.
1057 1057 *
1058   - * @return field address or -1 if the screen isn't formatted.
  1058 + * @return field address or -1 if the screen isn't formatted (sets errno).
1059 1059 *
1060 1060 */
1061   - LIB3270_EXPORT int lib3270_field_addr(H3270 *h, int baddr);
  1061 + LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr);
1062 1062  
1063 1063 LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr);
1064 1064  
1065 1065 /**
1066 1066 * @brief Get the length of the field at given buffer address.
1067 1067 *
1068   - * @param h Session handle.
1069   - * @param addr Buffer address of the field.
  1068 + * @param hSession Session handle.
  1069 + * @param addr Buffer address of the field.
1070 1070 *
1071   - * @return field length.
  1071 + * @return field length or -1 if invalid or not connected (sets errno).
1072 1072 *
1073 1073 */
1074 1074 LIB3270_EXPORT int lib3270_field_length(H3270 *h, int baddr);
... ...
src/lib3270/bounds.c
  Diff comments   View file @1fcc324
... ... @@ -34,16 +34,22 @@
34 34  
35 35 /*--[ Implement ]------------------------------------------------------------------------------------*/
36 36  
37   -LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *session, int baddr, int *start, int *end)
  37 +/**
  38 + * Get field region
  39 + *
  40 + * @param hSession Session handle.
  41 + * @param baddr Reference position to get the field start/stop offsets.
  42 + * @param start return location for start of selection, as a character offset.
  43 + * @param end return location for end of selection, as a character offset.
  44 + *
  45 + * @return -1 if invalid or not connected (sets errno).
  46 + *
  47 + */
  48 +LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *hSession, int baddr, int *start, int *end)
38 49 {
39 50 int first;
40 51  
41   - CHECK_SESSION_HANDLE(session);
42   -
43   - if(!lib3270_connected(session))
44   - return -1;
45   -
46   - first = lib3270_field_addr(session,baddr);
  52 + first = lib3270_field_addr(hSession,baddr);
47 53  
48 54 if(first < 0)
49 55 return -1;
... ... @@ -55,8 +61,8 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *session, int baddr, int *star
55 61  
56 62 if(end)
57 63 {
58   - int maxlen = (session->rows * session->cols)-1;
59   - *end = first + lib3270_field_length(session,first);
  64 + int maxlen = (hSession->rows * hSession->cols)-1;
  65 + *end = first + lib3270_field_length(hSession,first);
60 66 if(*end > maxlen)
61 67 *end = maxlen;
62 68 }
... ...
src/lib3270/ctlr.c
  Diff comments   View file @1fcc324
... ... @@ -483,6 +483,15 @@ LIB3270_EXPORT int lib3270_get_field_len(H3270 *hSession, int baddr)
483 483 return -1;
484 484 }
485 485  
  486 +/**
  487 + * @brief Find the buffer address of the field attribute for a given buffer address.
  488 + *
  489 + * @param hSession Session handle.
  490 + * @param addr Buffer address of the field.
  491 + *
  492 + * @return field address or -1 if the screen isn't formatted (sets errno).
  493 + *
  494 + */
486 495 LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr)
487 496 {
488 497 int sbaddr;
... ... @@ -503,6 +512,7 @@ LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr)
503 512 DEC_BA(baddr);
504 513 } while (baddr != sbaddr);
505 514  
  515 + errno = EINVAL;
506 516 return -1;
507 517 }
508 518  
... ... @@ -510,10 +520,13 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr)
510 520 {
511 521 int sbaddr;
512 522  
513   - CHECK_SESSION_HANDLE(hSession);
  523 + FAIL_IF_NOT_ONLINE(hSession);
514 524  
515   - if (!hSession->formatted)
  525 + if(!hSession->formatted)
  526 + {
  527 + errno = ENOTCONN;
516 528 return -1;
  529 + }
517 530  
518 531 sbaddr = baddr;
519 532 do
... ... @@ -523,12 +536,20 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr)
523 536 DEC_BA(baddr);
524 537 } while (baddr != sbaddr);
525 538  
  539 + errno = EINVAL;
526 540 return -1;
  541 +
527 542 }
528 543  
529 544  
530   -/*
531   - * Get Field width
  545 +/**
  546 + * @brief Get the length of the field at given buffer address.
  547 + *
  548 + * @param hSession Session handle.
  549 + * @param addr Buffer address of the field.
  550 + *
  551 + * @return field length or -1 if invalid or not connected (sets errno).
  552 + *
532 553 */
533 554 int lib3270_field_length(H3270 *hSession, int baddr)
534 555 {
... ... @@ -536,8 +557,6 @@ int lib3270_field_length(H3270 *hSession, int baddr)
536 557 int addr;
537 558 int width = 0;
538 559  
539   - CHECK_SESSION_HANDLE(hSession);
540   -
541 560 addr = find_field_attribute(hSession,baddr);
542 561  
543 562 if(addr < 0)
... ... @@ -553,6 +572,7 @@ int lib3270_field_length(H3270 *hSession, int baddr)
553 572 width++;
554 573 } while (addr != saddr);
555 574  
  575 + errno = EINVAL;
556 576 return -1;
557 577  
558 578 }
... ... @@ -566,11 +586,26 @@ unsigned char get_field_attribute(H3270 *hSession, int baddr)
566 586 return hSession->ea_buf[find_field_attribute(hSession,baddr)].fa;
567 587 }
568 588  
  589 +/**
  590 + * @brief Find the next unprotected field.
  591 + *
  592 + * @param hSession Session handle.
  593 + * @param baddr0 Search start addr (-1 to use current cursor position).
  594 + *
  595 + * @return address following the unprotected attribute byte, or 0 if no nonzero-width unprotected field can be found, -1 if not connected.
  596 + *
  597 + */
569 598 LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0)
570 599 {
571 600 register int baddr, nbaddr;
572 601  
573   - CHECK_SESSION_HANDLE(hSession);
  602 + FAIL_IF_NOT_ONLINE(hSession);
  603 +
  604 + if(!hSession->formatted)
  605 + {
  606 + errno = ENOTCONN;
  607 + return -1;
  608 + }
574 609  
575 610 if(baddr0 < 0)
576 611 baddr0 = hSession->cursor_addr;
... ... @@ -588,13 +623,12 @@ LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0)
588 623 }
589 624  
590 625 LIB3270_EXPORT int lib3270_get_is_protected_at(H3270 *h, int row, int col) {
591   - CHECK_SESSION_HANDLE(h);
592 626 return lib3270_get_is_protected(h, ((row-1) * h->cols) + (col-1));
593 627 }
594 628  
595 629 LIB3270_EXPORT int lib3270_get_is_protected(H3270 *hSession, int baddr)
596 630 {
597   - CHECK_SESSION_HANDLE(hSession);
  631 + FAIL_IF_NOT_ONLINE(hSession);
598 632  
599 633 if(baddr < 0)
600 634 baddr = hSession->cursor_addr;
... ... @@ -1163,10 +1197,8 @@ void ctlr_erase_all_unprotected(H3270 *hSession)
1163 1197 ALL_CHANGED(hSession);
1164 1198 }
1165 1199  
1166   -
1167   -
1168   -/*
1169   - * Process a 3270 Write command.
  1200 +/**
  1201 + * @brief Process a 3270 Write command.
1170 1202 */
1171 1203 enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean erase)
1172 1204 {
... ... @@ -1993,9 +2025,8 @@ enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean er
1993 2025 #undef ABORT_WRITEx
1994 2026 #undef ABORT_WRITE
1995 2027  
1996   -/*
1997   - * Write SSCP-LU data, which is quite a bit dumber than regular 3270
1998   - * output.
  2028 +/**
  2029 + * @brief Write SSCP-LU data, which is quite a bit dumber than regular 3270 output.
1999 2030 */
2000 2031 void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen)
2001 2032 {
... ... @@ -2095,7 +2126,9 @@ void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen)
2095 2126  
2096 2127 #if defined(X3270_DBCS) /*[*/
2097 2128  
2098   -/*
  2129 +/**
  2130 + * @brief Determine the DBCS state of a buffer location strictly by looking left.
  2131 + *
2099 2132 * Determine the DBCS state of a buffer location strictly by looking left.
2100 2133 * Used only to validate write operations.
2101 2134 * Returns only DBCS_LEFT, DBCS_RIGHT or DBCS_NONE.
... ... @@ -2367,7 +2400,7 @@ int ctlr_dbcs_postprocess(H3270 *hSession)
2367 2400 #endif /*]*/
2368 2401  
2369 2402 /**
2370   - * Process pending input.
  2403 + * @brief Process pending input.
2371 2404 *
2372 2405 * @param hSession Session handle.
2373 2406 */
... ... @@ -2464,10 +2497,8 @@ static void ctlr_blanks(H3270 *session)
2464 2497 ALL_CHANGED(session);
2465 2498 }
2466 2499  
2467   -
2468 2500 /**
2469   - * Change a character in the 3270 buffer, removes any field attribute defined at that location.
2470   - *
  2501 + * @brief Change a character in the 3270 buffer, removes any field attribute defined at that location.
2471 2502 *
2472 2503 */
2473 2504 void ctlr_add(H3270 *hSession, int baddr, unsigned char c, unsigned char cs)
... ...
src/lib3270/testprogram/testprogram.c
  Diff comments   View file @1fcc324
... ... @@ -11,7 +11,7 @@ int main(int numpar, char *param[])
11 11 {
12 12 H3270 * h;
13 13 int rc = 0;
14   - const char * url = getenv("TN3270URL");
  14 + const char * url = getenv("LIB3270_DEFAULT_HOST");
15 15  
16 16  
17 17 h = lib3270_session_new("");
... ...