Commit 1fcc324ed719e87d5e8f23927ff2549e7a8cbfe6
1 parent
d021aee6
Exists in
master
and in
3 other branches
Updating docs
Showing
4 changed files
with
75 additions
and
38 deletions
Show diff stats
src/include/lib3270.h
@@ -1052,23 +1052,23 @@ | @@ -1052,23 +1052,23 @@ | ||
1052 | /** | 1052 | /** |
1053 | * @brief Find the buffer address of the field attribute for a given buffer address. | 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 | LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr); | 1063 | LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr); |
1064 | 1064 | ||
1065 | /** | 1065 | /** |
1066 | * @brief Get the length of the field at given buffer address. | 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 | LIB3270_EXPORT int lib3270_field_length(H3270 *h, int baddr); | 1074 | LIB3270_EXPORT int lib3270_field_length(H3270 *h, int baddr); |
src/lib3270/bounds.c
@@ -34,16 +34,22 @@ | @@ -34,16 +34,22 @@ | ||
34 | 34 | ||
35 | /*--[ Implement ]------------------------------------------------------------------------------------*/ | 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 | int first; | 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 | if(first < 0) | 54 | if(first < 0) |
49 | return -1; | 55 | return -1; |
@@ -55,8 +61,8 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *session, int baddr, int *star | @@ -55,8 +61,8 @@ LIB3270_EXPORT int lib3270_get_field_bounds(H3270 *session, int baddr, int *star | ||
55 | 61 | ||
56 | if(end) | 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 | if(*end > maxlen) | 66 | if(*end > maxlen) |
61 | *end = maxlen; | 67 | *end = maxlen; |
62 | } | 68 | } |
src/lib3270/ctlr.c
@@ -483,6 +483,15 @@ LIB3270_EXPORT int lib3270_get_field_len(H3270 *hSession, int baddr) | @@ -483,6 +483,15 @@ LIB3270_EXPORT int lib3270_get_field_len(H3270 *hSession, int baddr) | ||
483 | return -1; | 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 | LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr) | 495 | LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr) |
487 | { | 496 | { |
488 | int sbaddr; | 497 | int sbaddr; |
@@ -503,6 +512,7 @@ LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr) | @@ -503,6 +512,7 @@ LIB3270_EXPORT int lib3270_field_addr(H3270 *hSession, int baddr) | ||
503 | DEC_BA(baddr); | 512 | DEC_BA(baddr); |
504 | } while (baddr != sbaddr); | 513 | } while (baddr != sbaddr); |
505 | 514 | ||
515 | + errno = EINVAL; | ||
506 | return -1; | 516 | return -1; |
507 | } | 517 | } |
508 | 518 | ||
@@ -510,10 +520,13 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr) | @@ -510,10 +520,13 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr) | ||
510 | { | 520 | { |
511 | int sbaddr; | 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 | return -1; | 528 | return -1; |
529 | + } | ||
517 | 530 | ||
518 | sbaddr = baddr; | 531 | sbaddr = baddr; |
519 | do | 532 | do |
@@ -523,12 +536,20 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr) | @@ -523,12 +536,20 @@ LIB3270_EXPORT int lib3270_field_attribute(H3270 *hSession, int baddr) | ||
523 | DEC_BA(baddr); | 536 | DEC_BA(baddr); |
524 | } while (baddr != sbaddr); | 537 | } while (baddr != sbaddr); |
525 | 538 | ||
539 | + errno = EINVAL; | ||
526 | return -1; | 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 | int lib3270_field_length(H3270 *hSession, int baddr) | 554 | int lib3270_field_length(H3270 *hSession, int baddr) |
534 | { | 555 | { |
@@ -536,8 +557,6 @@ int lib3270_field_length(H3270 *hSession, int baddr) | @@ -536,8 +557,6 @@ int lib3270_field_length(H3270 *hSession, int baddr) | ||
536 | int addr; | 557 | int addr; |
537 | int width = 0; | 558 | int width = 0; |
538 | 559 | ||
539 | - CHECK_SESSION_HANDLE(hSession); | ||
540 | - | ||
541 | addr = find_field_attribute(hSession,baddr); | 560 | addr = find_field_attribute(hSession,baddr); |
542 | 561 | ||
543 | if(addr < 0) | 562 | if(addr < 0) |
@@ -553,6 +572,7 @@ int lib3270_field_length(H3270 *hSession, int baddr) | @@ -553,6 +572,7 @@ int lib3270_field_length(H3270 *hSession, int baddr) | ||
553 | width++; | 572 | width++; |
554 | } while (addr != saddr); | 573 | } while (addr != saddr); |
555 | 574 | ||
575 | + errno = EINVAL; | ||
556 | return -1; | 576 | return -1; |
557 | 577 | ||
558 | } | 578 | } |
@@ -566,11 +586,26 @@ unsigned char get_field_attribute(H3270 *hSession, int baddr) | @@ -566,11 +586,26 @@ unsigned char get_field_attribute(H3270 *hSession, int baddr) | ||
566 | return hSession->ea_buf[find_field_attribute(hSession,baddr)].fa; | 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 | LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0) | 598 | LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0) |
570 | { | 599 | { |
571 | register int baddr, nbaddr; | 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 | if(baddr0 < 0) | 610 | if(baddr0 < 0) |
576 | baddr0 = hSession->cursor_addr; | 611 | baddr0 = hSession->cursor_addr; |
@@ -588,13 +623,12 @@ LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0) | @@ -588,13 +623,12 @@ LIB3270_EXPORT int lib3270_get_next_unprotected(H3270 *hSession, int baddr0) | ||
588 | } | 623 | } |
589 | 624 | ||
590 | LIB3270_EXPORT int lib3270_get_is_protected_at(H3270 *h, int row, int col) { | 625 | LIB3270_EXPORT int lib3270_get_is_protected_at(H3270 *h, int row, int col) { |
591 | - CHECK_SESSION_HANDLE(h); | ||
592 | return lib3270_get_is_protected(h, ((row-1) * h->cols) + (col-1)); | 626 | return lib3270_get_is_protected(h, ((row-1) * h->cols) + (col-1)); |
593 | } | 627 | } |
594 | 628 | ||
595 | LIB3270_EXPORT int lib3270_get_is_protected(H3270 *hSession, int baddr) | 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 | if(baddr < 0) | 633 | if(baddr < 0) |
600 | baddr = hSession->cursor_addr; | 634 | baddr = hSession->cursor_addr; |
@@ -1163,10 +1197,8 @@ void ctlr_erase_all_unprotected(H3270 *hSession) | @@ -1163,10 +1197,8 @@ void ctlr_erase_all_unprotected(H3270 *hSession) | ||
1163 | ALL_CHANGED(hSession); | 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 | enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean erase) | 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,9 +2025,8 @@ enum pds ctlr_write(H3270 *hSession, unsigned char buf[], int buflen, Boolean er | ||
1993 | #undef ABORT_WRITEx | 2025 | #undef ABORT_WRITEx |
1994 | #undef ABORT_WRITE | 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 | void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen) | 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,7 +2126,9 @@ void ctlr_write_sscp_lu(H3270 *hSession, unsigned char buf[], int buflen) | ||
2095 | 2126 | ||
2096 | #if defined(X3270_DBCS) /*[*/ | 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 | * Determine the DBCS state of a buffer location strictly by looking left. | 2132 | * Determine the DBCS state of a buffer location strictly by looking left. |
2100 | * Used only to validate write operations. | 2133 | * Used only to validate write operations. |
2101 | * Returns only DBCS_LEFT, DBCS_RIGHT or DBCS_NONE. | 2134 | * Returns only DBCS_LEFT, DBCS_RIGHT or DBCS_NONE. |
@@ -2367,7 +2400,7 @@ int ctlr_dbcs_postprocess(H3270 *hSession) | @@ -2367,7 +2400,7 @@ int ctlr_dbcs_postprocess(H3270 *hSession) | ||
2367 | #endif /*]*/ | 2400 | #endif /*]*/ |
2368 | 2401 | ||
2369 | /** | 2402 | /** |
2370 | - * Process pending input. | 2403 | + * @brief Process pending input. |
2371 | * | 2404 | * |
2372 | * @param hSession Session handle. | 2405 | * @param hSession Session handle. |
2373 | */ | 2406 | */ |
@@ -2464,10 +2497,8 @@ static void ctlr_blanks(H3270 *session) | @@ -2464,10 +2497,8 @@ static void ctlr_blanks(H3270 *session) | ||
2464 | ALL_CHANGED(session); | 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 | void ctlr_add(H3270 *hSession, int baddr, unsigned char c, unsigned char cs) | 2504 | void ctlr_add(H3270 *hSession, int baddr, unsigned char c, unsigned char cs) |
src/lib3270/testprogram/testprogram.c
@@ -11,7 +11,7 @@ int main(int numpar, char *param[]) | @@ -11,7 +11,7 @@ int main(int numpar, char *param[]) | ||
11 | { | 11 | { |
12 | H3270 * h; | 12 | H3270 * h; |
13 | int rc = 0; | 13 | int rc = 0; |
14 | - const char * url = getenv("TN3270URL"); | 14 | + const char * url = getenv("LIB3270_DEFAULT_HOST"); |
15 | 15 | ||
16 | 16 | ||
17 | h = lib3270_session_new(""); | 17 | h = lib3270_session_new(""); |